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.
# Migración de su AWS Encryption SDK
AWS Encryption SDK Admite múltiples [implementaciones de lenguajes de programación](programming-languages.md) interoperables, cada una de las cuales está desarrollada en un repositorio de código abierto en. GitHub Como [práctica recomendada](best-practices.md), le recomendamos que utilice la última versión de AWS Encryption SDK para cada lenguaje.
Puede actualizar de forma segura desde la versión 2.0. *x* o posterior AWS Encryption SDK a la última versión. Sin embargo, la 2.0. La versión *x* AWS Encryption SDK presenta nuevas e importantes funciones de seguridad, algunas de las cuales son cambios importantes. Para actualizar desde versiones anteriores a la 1.7.*x* a las versiones 2.0.*x* y versiones posteriores, primero debe actualizar a la última versión 1.*x*. Los temas de esta sección están diseñados para ayudarle a comprender los cambios, seleccionar la versión correcta para su aplicación y migrar de forma segura y correcta a las versiones más recientes de la AWS Encryption SDK.
Para obtener información sobre las versiones más importantes de AWS Encryption SDK, consulte[Versiones del AWS Encryption SDK](about-versions.md).
**importante**
No actualice directamente desde una versión anterior a la 1.7.*x* a la versión 2.0.*x* o posterior sin actualizar primero a la última versión 1.versión *x*. Si actualiza directamente a la versión 2.0. *x* o posterior y habilite todas las funciones nuevas de forma inmediata, AWS Encryption SDK no podrá descifrar el texto cifrado en versiones anteriores de. AWS Encryption SDK
**nota**
La versión más antigua de AWS Encryption SDK para .NET es la 3.0. *x*. Todas las AWS Encryption SDK versiones de.NET son compatibles con las mejores prácticas de seguridad introducidas en la versión 2.0. *x* de AWS Encryption SDK. Puede actualizar de forma segura a la última versión sin cambios de código o datos.
AWS CLI de cifrado: Al leer esta guía de migración, utilice la 1.7. *x* instrucciones de migración para AWS Encryption CLI 1.8. *x* y utilice la 2.0. *x* instrucciones de migración para AWS Encryption CLI 2.1. *x*. Para obtener más información, consulte [Versiones de la CLI AWS de cifrado](crypto-cli-versions.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.
**Nuevos usuarios**
Si es la primera vez que lo AWS Encryption SDK utiliza, instale la última versión de AWS Encryption SDK para su lenguaje de programación. Los valores predeterminados habilitan todas las funciones de seguridad del AWS Encryption SDK, incluido el cifrado con firma, la derivación de claves y el [compromiso de claves](concepts.md#key-commitment). del AWS Encryption SDK
**Usuarios actuales**
Se recomienda que lleva a cabo la actualización de la versión actual a la versión más reciente disponible lo antes posible. Todos los 1. Las versiones *x* de AWS Encryption SDK están en [end-of-support fase](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle), al igual que las versiones posteriores en algunos lenguajes de programación. Para obtener más información sobre el estado de soporte y mantenimiento de su lenguaje AWS Encryption SDK de programación, consulte [Compatibilidad y mantenimiento](introduction.md#support).
AWS Encryption SDK versiones 2.0. *x* y versiones posteriores ofrecen nuevas funciones de seguridad para ayudar a proteger sus datos. Sin embargo, AWS Encryption SDK la versión 2.0. *x* incluye cambios importantes que no son compatibles con versiones anteriores. Para garantizar una transición segura, comience por migrar de su versión actual a la última versión 1.*x* en su lenguaje de programación. Cuando su última versión 1.*x* está completamente implementada y funciona correctamente, puede migrar de forma segura a las versiones 2.0.*x* y versiones posteriores. Este [proceso de dos pasos](migration-guide.md) es fundamental, especialmente para las aplicaciones distribuidas.
*Para obtener más información sobre las características de AWS Encryption SDK seguridad que sustentan estos cambios, consulte el artículo [Mejora del cifrado del lado del cliente: compromiso explícito KeyIds y clave](https://aws.amazon.com/blogs/security/improved-client-side-encryption-explicit-keyids-and-key-commitment/) en el AWS blog sobre seguridad.*
¿Buscas ayuda para usar el? SDK de cifrado de AWS para Java AWS SDK for Java 2.x Consulte [Requisitos previos](java.md#java-prerequisites).
**Topics**
+ [¿Cómo migrar e implementar el AWS Encryption SDK](migration-guide.md)
+ [Actualización de los proveedores de claves AWS KMS maestras](migrate-mkps-v2.md)
+ [Actualización de los AWS KMS llaveros](migrate-keyrings-v2.md)
+ [Establecer su política de compromiso](migrate-commitment-policy.md)
+ [Solución de problemas de migración a las versiones más recientes](troubleshooting-migration.md)
# ¿Cómo migrar e implementar el AWS Encryption SDK
Al migrar desde una AWS Encryption SDK versión anterior a la 1.7. *x* a la versión 2.0. *x* o posterior, debe realizar la transición al cifrado de forma segura con un [compromiso de clave](concepts.md#key-commitment). De lo contrario, la aplicación encontrará textos cifrados que no podrá descifrar. Si utiliza proveedores de claves AWS KMS maestras, debe actualizar a nuevos constructores que creen proveedores de claves maestras en modo estricto o modo de descubrimiento.
**nota**
Este tema está diseñado para los usuarios que migran de versiones anteriores del AWS Encryption SDK a la versión 2.0.*x* o posterior. Si es la primera vez que utiliza el AWS Encryption SDK, puede empezar a utilizar inmediatamente la última versión disponible con la configuración predeterminada.
Para evitar una situación crítica en la que no pueda descifrar el texto cifrado que necesita leer, le recomendamos que migre e implemente en varias etapas distintas. Compruebe que cada etapa esté completa y completamente implementada antes de comenzar la siguiente. Esto es particularmente importante en el caso de las aplicaciones distribuidas con varios hosts.
## Etapa 1: actualice su aplicación a la última versión 1.*x*
Actualice a la versión más reciente 1.*x* para su lenguaje de programación. Pruébelo detenidamente, implemente los cambios y confirme que la actualización se ha propagado a todos los hosts de destino antes de comenzar la fase 2.
**importante**
Verifique que su última versión 1.*x* es 1.7.*x* o una versión posterior de AWS Encryption SDK.
La última 1. Las versiones *x* AWS Encryption SDK son compatibles con versiones anteriores AWS Encryption SDK y posteriores con las versiones 2.0. *x* y versiones posteriores. Incluyen las características nuevas que están presentes en la versión 2.0.*x*, pero incluyen valores predeterminados seguros diseñados para esta migración. Permiten actualizar sus proveedores de claves AWS KMS maestras, si es necesario, e implementarlos completamente con conjuntos de algoritmos que pueden descifrar el texto cifrado con un compromiso clave.
+ Sustituya los elementos obsoletos, incluidos los constructores de proveedores de claves maestras heredados de AWS KMS . En [Python](https://docs.python.org/3/library/warnings.html), asegúrese de activar las advertencias de obsolescencia. Elementos de código que están en desuso en la última versión 1.*x* se han eliminado de las versiones 2.0.*x* y versiones posteriores.
+ Establezca explícitamente su política de compromiso en `ForbidEncryptAllowDecrypt`. Aunque este es el único valor válido en el último número 1. *x* versiones, esta configuración es necesaria cuando se utiliza la versión APIs introducida en esta versión. Evita que su aplicación rechace el texto cifrado sin compromiso clave al migrar a la versión 2.0.*x* y versiones posteriores. Para obtener más información, consulte [Establecer su política de compromiso](migrate-commitment-policy.md).
+ Si utiliza proveedores de claves AWS KMS maestras, debe actualizar los proveedores de claves maestras antiguos a proveedores de claves maestras que admitan el *modo estricto y el modo* de *descubrimiento*. Esta actualización es necesaria para la SDK de cifrado de AWS para Java SDK de cifrado de AWS para Python, y la CLI de AWS cifrado. Si utiliza proveedores de claves maestras en modo de detección, le recomendamos que implemente el filtro de detección que limite las claves de encapsulamiento utilizadas a esas claves en particular Cuentas de AWS. Esta actualización es opcional, pero es una [práctica recomendada](best-practices.md). Para obtener más información, consulte [Actualización de los proveedores de claves AWS KMS maestras](migrate-mkps-v2.md).
+ Si utiliza conjuntos de [claves de detección de AWS KMS](use-kms-keyring.md#kms-keyring-discovery), le recomendamos que incluya un filtro de detección que limite las claves de encapsulamiento utilizadas en el descifrado a aquellas en particular Cuentas de AWS. Esta actualización es opcional, pero es una [práctica recomendada](best-practices.md). Para obtener más información, consulte [Actualización de los AWS KMS llaveros](migrate-keyrings-v2.md).
## Etapa 2: actualice la aplicación a la versión más reciente
Después de implementar la última versión 1.*x* correctamente en todos los hosts, puede actualizarla a la versión 2.0.*x* y versiones posteriores. Versión 2.0. *x* incluye cambios importantes en todas las versiones anteriores de AWS Encryption SDK. Sin embargo, si realiza los cambios de código recomendados en la fase 1, puede evitar errores al migrar a la última versión.
Antes de actualizar a la última versión, compruebe que su política de compromiso esté establecida de forma coherente en `ForbidEncryptAllowDecrypt`. A continuación, dependiendo de su configuración de datos, puede migrar a su propio ritmo a `RequireEncryptAllowDecrypt` y luego a la configuración predeterminada, `RequireEncryptRequireDecrypt`. Recomendamos una serie de pasos de transición como el siguiente patrón.
1. Comience con su [política de compromiso](migrate-commitment-policy.md) establecida en `ForbidEncryptAllowDecrypt`. El AWS Encryption SDK puede descifrar los mensajes con un compromiso clave, pero aún no lo hace con un compromiso clave.
1. Cuando esté listo, actualice su política de compromisos a `RequireEncryptAllowDecrypt`. AWS Encryption SDK Comienza a cifrar sus datos con un [compromiso clave](concepts.md#key-commitment). Puede descifrar texto cifrado con y sin compromiso clave.
Antes de actualizar su política de compromiso a`RequireEncryptAllowDecrypt`, compruebe que su última versión 1.*x* está implementada en todos los hosts, incluidos los servidores de cualquier aplicación que descifre el texto cifrado que genere. Versiones AWS Encryption SDK anteriores a la 1.7. *x* no puede descifrar los mensajes cifrados con un compromiso de clave.
También es un buen momento para añadir métricas a su aplicación para medir si sigue procesando texto cifrado sin compromiso clave. Esto lo ayudará a determinar cuándo es seguro actualizar la configuración de su política de compromiso a `RequireEncryptRequireDecrypt`. En el caso de algunas aplicaciones, como las que cifran los mensajes de una cola de Amazon SQS, esto puede implicar esperar el tiempo suficiente para volver a cifrar o eliminar todo el texto cifrado en versiones anteriores. En el caso de otras aplicaciones, como los objetos S3 cifrados, es posible que tenga que descargar, volver a cifrar y volver a cargar todos los objetos.
1. Cuando esté seguro de que no tiene ningún mensaje cifrado sin un compromiso clave, puede actualizar su política de compromiso a `RequireEncryptRequireDecrypt`. Este valor garantiza que sus datos estén siempre cifrados y descifrados con el compromiso clave. Esta configuración es la predeterminada, por lo que no es necesario que la establezca de forma explícita, pero le recomendamos que la configure. Una configuración explícita [ayudará a la depuración](troubleshooting-migration.md) y a cualquier posible reversión que pueda ser necesaria si su aplicación encuentra texto cifrado sin compromiso clave.
# Actualización de los proveedores de claves AWS KMS maestras
Para migrar a la última versión 1. a la versión *x* y AWS Encryption SDK, a continuación, a la versión 2.0. *x* o posterior, debe sustituir los proveedores de claves AWS KMS maestras antiguos por proveedores de claves maestras creados explícitamente en [*modo estricto o modo* de *descubrimiento*](about-versions.md#changes-to-mkps). Los proveedores de claves maestras antiguos están en desuso en la versión 1.7.*x* y se eliminaron en la versión 2.0.*x*. Este cambio es necesario para las aplicaciones y los scripts que utilizan el [SDK de cifrado de AWS para Java](java.md), el [SDK de cifrado de AWS para Python](python.md), y la [CLI de cifrado de AWS](crypto-cli.md). Los ejemplos de esta sección le mostrarán cómo actualizar el código.
**nota**
En Python, [active las advertencias de obsolescencia](https://docs.python.org/3/library/warnings.html). Esto le ayudará a identificar las partes del código que necesita actualizar.
Si utiliza una clave AWS KMS maestra (no un proveedor de claves maestras), puede omitir este paso. AWS KMS las claves maestras no están en desuso ni se han eliminado. Solo cifran y descifran con las claves de encapsulamiento que usted especifique.
Los ejemplos de esta sección se centran en los elementos del código que debe cambiar. Para ver un ejemplo completo del código actualizado, consulta la sección de ejemplos del GitHub repositorio correspondiente a tu [lenguaje de programación](programming-languages.md). Además, estos ejemplos suelen utilizar la clave ARNs para representar AWS KMS keys. Al crear un proveedor de claves maestras para el cifrado, puede utilizar cualquier [identificador de AWS KMS clave](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id) válido para representar un AWS KMS key . Al crear un proveedor de claves maestras para el descifrado, debe utilizar un ARN de clave.
**Más información sobre migración**
Para todos los AWS Encryption SDK usuarios, obtén información sobre cómo establecer tu política de compromiso en[Establecer su política de compromiso](migrate-commitment-policy.md).
Para SDK de cifrado de AWS para C los SDK de cifrado de AWS para JavaScript usuarios finales, infórmese sobre una actualización opcional de los llaveros. [Actualización de los AWS KMS llaveros](migrate-keyrings-v2.md)
**Topics**
+ [Migración al modo estricto](#migrate-mkp-strict-mode)
+ [Migración al modo de detección](#migrate-mkp-discovery-mode)
## Migración al modo estricto
Después de actualizar a la última versión 1. versión *x* de AWS Encryption SDK, sustituya sus proveedores de claves maestras antiguos por proveedores de claves maestras en modo estricto. En el modo estricto, debe especificar las claves de encapsulamiento que se utilizarán al cifrar y descifrar. AWS Encryption SDK Utiliza solo las claves de empaquetado que especifique. Los proveedores de claves maestras en desuso pueden descifrar los datos utilizando cualquier AWS KMS key sistema que cifre una clave de datos, incluso AWS KMS keys en diferentes regiones Cuentas de AWS .
Los proveedores de claves maestras en modo estricto se introducen en la AWS Encryption SDK versión 1.7. *x*. Sustituyen a los proveedores de claves maestras antiguos, que están en desuso en la versión 1.7.*x* y se eliminaron en la versión 2.0.*x*. Utilizar proveedores de claves maestras en modo estricto es una AWS Encryption SDK [buena práctica](best-practices.md).
El código siguiente crea un proveedor de claves maestras en modo estricto que puede utilizar para cifrar y descifrar.
------
#### [ Java ]
Este ejemplo representa el código de una aplicación que utiliza la versión 1.6.2 o anterior de SDK de cifrado de AWS para Java.
Este código usa el `KmsMasterKeyProvider.builder()` método para crear una instancia de un proveedor de claves AWS KMS maestras que usa una AWS KMS key como clave de empaquetado.
```
// Create a master key provider
// Replace the example key ARN with a valid one
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder()
.withKeysForEncryption(awsKmsKey)
.build();
```
Este ejemplo representa el código de una aplicación que usa la versión 1.7.*x* o una versión posterior de SDK de cifrado de AWS para Java . [Para ver un ejemplo completo, consulta BasicEncryptionExample .java.](https://github.com/aws/aws-encryption-sdk-java/blob/master/src/examples/java/com/amazonaws/crypto/examples/v2/BasicEncryptionExample.java)
Los métodos `Builder.build()` y `Builder.withKeysForEncryption()` utilizados en el ejemplo anterior están obsoletos en la versión 1.7.*x* y se han eliminado de la versión 2.0.*x*.
Para actualizar a un proveedor de claves maestras en modo estricto, este código reemplaza las llamadas a métodos obsoletos por una llamada al método `Builder.buildStrict()` nuevo. En este ejemplo se especifica una AWS KMS key como clave de ajuste, pero el `Builder.buildStrict()` método puede tomar una lista de múltiples AWS KMS keys.
```
// Create a master key provider in strict mode
// Replace the example key ARN with a valid one from your Cuenta de AWS.
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder()
.buildStrict(awsKmsKey);
```
------
#### [ Python ]
Este ejemplo representa el código de una aplicación que utiliza la versión 1.4.1 de SDK de cifrado de AWS para Python. Este código usa `KMSMasterKeyProvider`, que está obsoleto en la versión 1.7.*x* y eliminado de la versión 2.0.*x*. Al descifrar, utiliza cualquier clave AWS KMS key que haya cifrado una clave de datos sin tener en cuenta la AWS KMS keys que especifique.
Tenga en cuenta que `KMSMasterKey` no está en desuso ni se ha eliminado. Al cifrar y descifrar, utiliza únicamente la que usted especifique. AWS KMS key
```
# Create a master key provider
# Replace the example key ARN with a valid one
key_1 = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
key_2 = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"
aws_kms_master_key_provider = KMSMasterKeyProvider(
key_ids=[key_1, key_2]
)
```
Este ejemplo representa el código de una aplicación que usa la versión 1.7.*x* de SDK de cifrado de AWS para Python. Para ver un ejemplo completo, consulte [basic\$1encryption.py](https://github.com/aws/aws-encryption-sdk-python/blob/master/examples/src/legacy/basic_encryption.py).
Para actualizar a un proveedor de claves maestras en modo estricto, este código reemplaza la llamada a `KMSMasterKeyProvider()` por una llamada a `StrictAwsKmsMasterKeyProvider()`.
```
# Create a master key provider in strict mode
# Replace the example key ARNs with valid values from your Cuenta de AWS
key_1 = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
key_2 = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"
aws_kms_master_key_provider = StrictAwsKmsMasterKeyProvider(
key_ids=[key_1, key_2]
)
```
------
#### [ AWS Encryption CLI ]
En este ejemplo se muestra cómo cifrar y descifrar mediante la AWS CLI de cifrado, versión 1.1.7 o anterior.
En la versión 1.1.7 y anteriores, al cifrar, se especifican una o más claves maestras (o *claves de encapsulamiento*), como una AWS KMS key. Al descifrar, no puede especificar ninguna clave de encapsulamiento a menos que utilice un proveedor de claves maestras personalizado. La CLI de AWS cifrado puede usar cualquier clave de empaquetado que cifre una clave de datos.
```
\\ Replace the example key ARN with a valid one
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
\\ Encrypt your plaintext data
$ aws-encryption-cli --encrypt \
--input hello.txt \
--master-keys key=$keyArn \
--metadata-output ~/metadata \
--encryption-context purpose=test \
--output .
\\ Decrypt your ciphertext
$ aws-encryption-cli --decrypt \
--input hello.txt.encrypted \
--encryption-context purpose=test \
--metadata-output ~/metadata \
--output .
```
En este ejemplo se muestra cómo cifrar y descifrar mediante la versión 1.7 de la AWS CLI de cifrado. *x o posterior*. Para ver ejemplos completos, consulte [Ejemplos de la CLI AWS de cifrado](crypto-cli-examples.md).
El parámetro `--master-keys` está obsoleto en la versión 1.7.*x* y se eliminó en la versión 2.0.*x*. Se ha sustituido por el parámetro `--wrapping-keys`, que es obligatorio en los comandos de cifrado y descifrado. Este parámetro admite el modo estricto y el modo de detección. El modo estricto es una práctica AWS Encryption SDK recomendada que garantiza que utilice la clave de embalaje deseada.
Para actualizar al *modo estricto*, utilice el atributo **key** del `--wrapping-keys` parámetro para especificar una clave de encapsulamiento al cifrar y descifrar.
```
\\ Replace the example key ARN with a valid value
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
\\ Encrypt your plaintext data
$ aws-encryption-cli --encrypt \
--input hello.txt \
--wrapping-keys key=$keyArn \
--metadata-output ~/metadata \
--encryption-context purpose=test \
--output .
\\ Decrypt your ciphertext
$ aws-encryption-cli --decrypt \
--input hello.txt.encrypted \
--wrapping-keys key=$keyArn \
--encryption-context purpose=test \
--metadata-output ~/metadata \
--output .
```
------
## Migración al modo de detección
A partir de la versión 1.7. *x*, se recomienda utilizar AWS Encryption SDK [el](best-practices.md) *modo estricto* para los proveedores de claves AWS KMS maestras, es decir, especificar las claves de empaquetado al cifrar y descifrar. Siempre debe especificar las claves de encapsulamiento al cifrar. Sin embargo, hay situaciones en las que no es práctico especificar ARNs la clave AWS KMS keys para el descifrado. Por ejemplo, si utiliza alias para identificar AWS KMS keys al cifrar, pierde la ventaja de los alias si tiene que incluir la clave al descifrar. ARNs Además, dado que los proveedores de claves maestras en el modo de detección se comportan igual que los proveedores de claves maestras originales, puede utilizarlos temporalmente como parte de su estrategia de migración y, posteriormente, pasarse a proveedores de claves maestras en modo estricto.
En casos como este, puede utilizar los proveedores de claves maestras en el *modo de detección*. Estos proveedores de claves maestras no permiten especificar claves de encapsulamiento, por lo que no puede utilizarlas para cifrar. Al descifrar, pueden usar cualquier clave de encapsulamiento que cifre una clave de datos. Sin embargo, a diferencia de los proveedores de claves maestras tradicionales, que se comportan de la misma manera, se crean en modo de detección de forma explícita. Al utilizar proveedores de claves maestras en modo de detección, puede limitar las claves de ajuste que se pueden usar para aquellas en particular Cuentas de AWS. Este filtro de detección es opcional, pero es una práctica recomendada. Para obtener información sobre particiones y cuentas de AWS , consulte [Nombres de recursos de Amazon](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html#arns-syntax) en *Referencia general de AWS*.
En los ejemplos siguientes se crea un proveedor de clave AWS KMS maestra en modo estricto para el cifrado y un proveedor de clave AWS KMS maestra en modo de detección para descifrar. El proveedor de claves maestras en el modo de detección utiliza un filtro de detección para limitar las claves de encapsulamiento utilizadas para descifrar a la `aws` partición y a un ejemplo concreto Cuentas de AWS. Si bien el filtro de cuentas no es necesario en este ejemplo tan sencillo, es una práctica recomendada que resulta muy beneficiosa cuando una aplicación cifra los datos y otra los descifra.
------
#### [ Java ]
Este ejemplo representa el código de una aplicación que usa la versión 1.7.*x* o una versión posterior de SDK de cifrado de AWS para Java. [Para ver un ejemplo completo, consulte DiscoveryDecryptionExample .java.](https://github.com/aws/aws-encryption-sdk-java/blob/master/src/examples/java/com/amazonaws/crypto/examples/)
Para crear una instancia de un proveedor de claves maestras en modo estricto para el cifrado, en este ejemplo se utiliza el método `Builder.buildStrict()`. Para crear una instancia de un proveedor de claves maestras en modo de detección para el descifrado, se utiliza el método `Builder.buildDiscovery()`. El `Builder.buildDiscovery()` método utiliza una `DiscoveryFilter` que limita el AWS Encryption SDK to AWS KMS keys en la AWS partición y las cuentas especificadas.
```
// Create a master key provider in strict mode for encrypting
// Replace the example alias ARN with a valid one from your Cuenta de AWS.
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias";
KmsMasterKeyProvider encryptingKeyProvider = KmsMasterKeyProvider.builder()
.buildStrict(awsKmsKey);
// Create a master key provider in discovery mode for decrypting
// Replace the example account IDs with valid values.
DiscoveryFilter accounts = new DiscoveryFilter("aws", Arrays.asList("111122223333", "444455556666"));
KmsMasterKeyProvider decryptingKeyProvider = KmsMasterKeyProvider.builder()
.buildDiscovery(accounts);
```
------
#### [ Python ]
Este ejemplo representa el código de una aplicación que usa la versión 1.7.*x* o una versión posterior de SDK de cifrado de AWS para Python . Para ver un ejemplo completo, consulte: [discovery\$1kms\$1provider.py](https://github.com/aws/aws-encryption-sdk-python/blob/master/examples/src/legacy/discovery_kms_provider.py).
Para crear un proveedor de claves maestras en modo estricto para el cifrado, en este ejemplo se utiliza el `StrictAwsKmsMasterKeyProvider`. Para crear un proveedor de claves maestras en modo de descubrimiento para el descifrado, utiliza `DiscoveryAwsKmsMasterKeyProvider` un `DiscoveryFilter` que limita el AWS Encryption SDK to AWS KMS keys en la AWS partición y las cuentas especificadas.
```
# Create a master key provider in strict mode
# Replace the example key ARN and alias ARNs with valid values from your Cuenta de AWS.
key_1 = "arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias"
key_2 = "arn:aws:kms:us-west-2:444455556666:key/1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d"
aws_kms_master_key_provider = StrictAwsKmsMasterKeyProvider(
key_ids=[key_1, key_2]
)
# Create a master key provider in discovery mode for decrypting
# Replace the example account IDs with valid values
accounts = DiscoveryFilter(
partition="aws",
account_ids=["111122223333", "444455556666"]
)
aws_kms_master_key_provider = DiscoveryAwsKmsMasterKeyProvider(
discovery_filter=accounts
)
```
------
#### [ AWS Encryption CLI ]
En este ejemplo se muestra cómo cifrar y descifrar mediante la versión 1.7 de la AWS CLI de cifrado. *x o posterior*. A partir de la versión 1.7.*x*, el parámetro `--wrapping-keys` es obligatorio para cifrar y descifrar. El parámetro `--wrapping-keys` admite el modo estricto y el modo de detección. Para ver ejemplos completos, consulte [Ejemplos de la CLI AWS de cifrado](crypto-cli-examples.md).
Al cifrar, en este ejemplo se especifica una clave de encapsulamiento, que es obligatoria. Al descifrar, elige explícitamente el *modo de detección* mediante el atributo `discovery` del parámetro `--wrapping-keys` con un valor de `true`.
Para limitar las claves de empaquetado que AWS Encryption SDK pueden usar en el modo de detección a aquellas en particular Cuentas de AWS, en este ejemplo se utilizan los `discovery-account` atributos `discovery-partition` y del `--wrapping-keys` parámetro. Estos atributos opcionales solo son válidos cuando el atributo `discovery` está establecido en `true`. Debe utilizar los atributos `discovery-partition` y `discovery-account` juntos; ninguno de los dos es válido por sí solo.
```
\\ Replace the example key ARN with a valid value
$ keyAlias=arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias
\\ Encrypt your plaintext data
$ aws-encryption-cli --encrypt \
--input hello.txt \
--wrapping-keys key=$keyAlias \
--metadata-output ~/metadata \
--encryption-context purpose=test \
--output .
\\ Decrypt your ciphertext
\\ Replace the example account IDs with valid values
$ aws-encryption-cli --decrypt \
--input hello.txt.encrypted \
--wrapping-keys discovery=true \
discovery-partition=aws \
discovery-account=111122223333 \
discovery-account=444455556666 \
--encryption-context purpose=test \
--metadata-output ~/metadata \
--output .
```
------
# Actualización de los AWS KMS llaveros
AWS KMS Los anillos de claves de [SDK de cifrado de AWS para C](c-language.md), los de [.NET](dot-net.md) y el AWS Encryption SDK son [SDK de cifrado de AWS para JavaScript](javascript.md)compatibles con [las mejores prácticas](best-practices.md), ya que permiten especificar claves de empaquetado al cifrar y descifrar. Si crea un [conjunto de claves de detección de AWS KMS](use-kms-keyring.md#kms-keyring-discovery), lo hace de forma explícita.
**nota**
La versión más antigua de AWS Encryption SDK para .NET es la 3.0. *x*. Todas las AWS Encryption SDK versiones de.NET son compatibles con las mejores prácticas de seguridad introducidas en la versión 2.0. *x* de AWS Encryption SDK. Puede actualizar de forma segura a la última versión sin cambios de código o datos.
Al actualizar a la última versión 1. versión *x* de AWS Encryption SDK, puede utilizar un [filtro de descubrimiento](use-kms-keyring.md#kms-keyring-discovery) para limitar las claves de empaquetado que un conjunto de claves de [AWS KMS descubrimiento o un](use-kms-keyring.md#kms-keyring-discovery) conjunto de [claves de descubrimiento AWS KMS regional](use-kms-keyring.md#kms-keyring-regional) utiliza al descifrar a esas en particular. Cuentas de AWS[Se recomienda filtrar un conjunto de claves de detección. AWS Encryption SDK](best-practices.md)
Los ejemplos de esta sección le mostrarán cómo añadir el filtro de detección a un conjunto de claves de detección regional AWS KMS .
**Obtenga más información sobre la migración**
Para todos los AWS Encryption SDK usuarios, infórmese sobre cómo establecer su política de compromiso. [Establecer su política de compromiso](migrate-commitment-policy.md)
Para SDK de cifrado de AWS para Java SDK de cifrado de AWS para Python, y los usuarios de CLI de AWS cifrado, infórmese sobre la actualización necesaria para los proveedores de claves maestras en[Actualización de los proveedores de claves AWS KMS maestras](migrate-mkps-v2.md).
Es posible que tenga un código como el siguiente en su aplicación. En este ejemplo, se crea un conjunto de claves de detección regional AWS KMS que solo puede usar claves de encapsulamiento en la región del oeste de EE. UU. (Oregón) (us-west-2). Este ejemplo representa el código de las AWS Encryption SDK versiones anteriores a la 1.7. *x*. Sin embargo, sigue siendo válido en las versiones 1.7.*x* y versiones posteriores.
------
#### [ C ]
```
struct aws_cryptosdk_keyring *kms_regional_keyring = Aws::Cryptosdk::KmsKeyring::Builder()
.WithKmsClient(create_kms_client(Aws::Region::US_WEST_2)).BuildDiscovery());
```
------
#### [ JavaScript Browser ]
```
const clientProvider = getClient(KMS, { credentials })
const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringBrowser({ clientProvider, discovery })
```
------
#### [ JavaScript Node.js ]
```
const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringNode({ clientProvider, discovery })
```
------
A partir de la versión 1.7. *x*, puede añadir un filtro de detección a cualquier conjunto de claves de AWS KMS detección. Este filtro de detección limita las AWS KMS keys que se AWS Encryption SDK pueden utilizar para el descifrado a las de la partición y las cuentas especificadas. Antes de usar este código, cambie la partición, si es necesario, y sustituya la cuenta IDs de ejemplo por una válida.
------
#### [ C ]
Para ver un ejemplo completo, consulte: [kms\$1discovery.cpp](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/kms_discovery.cpp).
```
std::shared_ptr discovery_filter(
KmsKeyring::DiscoveryFilter::Builder("aws")
.AddAccount("111122223333")
.AddAccount("444455556666")
.Build());
struct aws_cryptosdk_keyring *kms_regional_keyring = Aws::Cryptosdk::KmsKeyring::Builder()
.WithKmsClient(create_kms_client(Aws::Region::US_WEST_2)).BuildDiscovery(discovery_filter));
```
------
#### [ JavaScript Browser ]
```
const clientProvider = getClient(KMS, { credentials })
const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringBrowser(clientProvider, {
discovery,
discoveryFilter: { accountIDs: ['111122223333', '444455556666'], partition: 'aws' }
})
```
------
#### [ JavaScript Node.js ]
Para ver un ejemplo completo, consulte: [kms\$1filtered\$1discovery.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-node/src/kms_filtered_discovery.ts).
```
const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringNode({
clientProvider,
discovery,
discoveryFilter: { accountIDs: ['111122223333', '444455556666'], partition: 'aws' }
})
```
------
# Establecer su política de compromiso
El [compromiso clave](concepts.md#key-commitment) garantiza que sus datos cifrados siempre se descifren en el mismo texto no cifrado. Para proporcionar esta propiedad de seguridad, a partir de la versión 1.7. *x*, AWS Encryption SDK utiliza nuevos [conjuntos de algoritmos](supported-algorithms.md) con un compromiso clave. Para determinar si sus datos están cifrados y descifrados con un compromiso clave, utilice la opción de configuración de la [política de compromiso](concepts.md#commitment-policy). [Cifrar y descifrar los datos con un compromiso clave es una AWS Encryption SDK práctica recomendada.](best-practices.md)
Establecer una política de compromiso es una parte importante del segundo paso del proceso de migración: migrar desde la última versión. *x* versiones de las dos AWS Encryption SDK versiones 2.0. *x* y versiones posteriores. Tras configurar y cambiar la política de compromiso, asegúrese de probar minuciosamente la aplicación antes de implementarla en producción. Para obtener orientación sobre la migración, consulte[¿Cómo migrar e implementar el AWS Encryption SDK](migration-guide.md).
La configuración de la política de compromiso tiene tres valores válidos en las versiones 2.0.*x* y versiones posteriores. En las últimas versiones 1.*x* (empezando por la versión 1.7.*x*), solo `ForbidEncryptAllowDecrypt` es válida.
+ `ForbidEncryptAllowDecrypt`— AWS Encryption SDK No se puede cifrar con un compromiso de clave. Puede descifrar textos cifrados, cifrados con o sin compromiso clave.
En las últimas versiones 1.*x*, este es el único valor válido. Garantiza que no se cifre con compromiso clave hasta que esté totalmente preparado para descifrar con compromiso clave. Si se establece este valor de forma explícita, se evita que la política de compromiso se modifique automáticamente a `require-encrypt-require-decrypt` cuando actualice su versión a la versión 2.0.*x* o posterior. En su lugar, puede [migrar su política de compromisos](#migrate-commitment-policy) por etapas.
+ `RequireEncryptAllowDecrypt`— AWS Encryption SDK Siempre cifra con un compromiso de clave. Puede descifrar textos cifrados, cifrados con o sin compromiso clave. Este valor se añade en la versión 2.0.*x*.
+ `RequireEncryptRequireDecrypt`— AWS Encryption SDK Siempre cifra y descifra con compromiso de clave. Este valor se añade en la versión 2.0.*x*. Es el valor predeterminado en las versiones 2.0.*x* y posteriores.
En las últimas versiones 1.*x*, el único valor válido de la política de compromiso es `ForbidEncryptAllowDecrypt`. Después de migrar hasta la versión 2.0.*x* o una versión posterior, puede [cambiar su política de compromisos por etapas](migration-guide.md) a medida que esté preparado. No actualice su política de compromisos a `RequireEncryptRequireDecrypt` hasta que esté seguro de que no tiene ningún mensaje cifrado sin un compromiso clave.
Estos ejemplos le muestran cómo establecer su política de compromiso en la última versión 1.*x* y en las versiones 2.0.*x* y versiones posteriores. La técnica depende del lenguaje de programación.
**Más información sobre la migración**
Para SDK de cifrado de AWS para Java SDK de cifrado de AWS para Python, y la CLI de AWS cifrado, obtenga información sobre los cambios necesarios en los proveedores de claves maestras en[Actualización de los proveedores de claves AWS KMS maestras](migrate-mkps-v2.md).
Para SDK de cifrado de AWS para C y SDK de cifrado de AWS para JavaScript, infórmese sobre una actualización opcional de los llaveros. [Actualización de los AWS KMS llaveros](migrate-keyrings-v2.md)
## ¿Cómo establecer su política de compromiso?
La técnica que se utiliza para establecer la política de compromiso varía ligeramente en función de la implementación en cada lenguaje. En estos ejemplos de .NET puede ver cómo: Antes de cambiar su política de compromiso, revise el enfoque de varias etapas que se incluye en [Cómo migrar e implementar](migration-guide.md).
------
#### [ C ]
A partir de la versión 1.7. *x* SDK de cifrado de AWS para C, utiliza la `aws_cryptosdk_session_set_commitment_policy` función para establecer la política de compromiso en sus sesiones de cifrado y descifrado. La política de compromiso que establezca se aplica a todas las operaciones de cifrado y descifrado realizadas en esa sesión.
Las funciones `aws_cryptosdk_session_new_from_keyring` y `aws_cryptosdk_session_new_from_cmm` están en desuso en la versión 1.7.*x* y se eliminaron en la versión 2.0.*x*. Estas funciones se sustituyen por funciones `aws_cryptosdk_session_new_from_keyring_2` y `aws_cryptosdk_session_new_from_cmm_2` que devuelven una sesión.
Cuando usa `aws_cryptosdk_session_new_from_keyring_2` y `aws_cryptosdk_session_new_from_cmm_2` en las últimas versiones 1.*x*, debe llamar a la función `aws_cryptosdk_session_set_commitment_policy` con el valor de la política de compromiso `COMMITMENT_POLICY_FORBID_ENCRYPT_ALLOW_DECRYPT`. En versiones 2.0.*x* y versiones posteriores, llamar a esta función es opcional y toma todos los valores válidos. La política de compromiso predeterminada para las versiones 2.0.*x* y versiones posteriores es `COMMITMENT_POLICY_REQUIRE_ENCRYPT_REQUIRE_DECRYPT`.
Para obtener un ejemplo completo, consulte [string.cpp](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/string.cpp).
```
/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();
/* Create an AWS KMS keyring */
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);
/* Create an encrypt session with a CommitmentPolicy setting */
struct aws_cryptosdk_session *encrypt_session = aws_cryptosdk_session_new_from_keyring_2(
alloc, AWS_CRYPTOSDK_ENCRYPT, kms_keyring);
aws_cryptosdk_keyring_release(kms_keyring);
aws_cryptosdk_session_set_commitment_policy(encrypt_session,
COMMITMENT_POLICY_FORBID_ENCRYPT_ALLOW_DECRYPT);
...
/* Encrypt your data */
size_t plaintext_consumed_output;
aws_cryptosdk_session_process(encrypt_session,
ciphertext_output,
ciphertext_buf_sz_output,
ciphertext_len_output,
plaintext_input,
plaintext_len_input,
&plaintext_consumed_output)
...
/* Create a decrypt session with a CommitmentPolicy setting */
struct aws_cryptosdk_keyring *kms_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn);
struct aws_cryptosdk_session *decrypt_session = *aws_cryptosdk_session_new_from_keyring_2(
alloc, AWS_CRYPTOSDK_DECRYPT, kms_keyring);
aws_cryptosdk_keyring_release(kms_keyring);
aws_cryptosdk_session_set_commitment_policy(decrypt_session,
COMMITMENT_POLICY_FORBID_ENCRYPT_ALLOW_DECRYPT);
/* Decrypt your ciphertext */
size_t ciphertext_consumed_output;
aws_cryptosdk_session_process(decrypt_session,
plaintext_output,
plaintext_buf_sz_output,
plaintext_len_output,
ciphertext_input,
ciphertext_len_input,
&ciphertext_consumed_output)
```
------
#### [ C\$1 / .NET ]
El `require-encrypt-require-decrypt` valor es la política de compromiso predeterminada en todas las versiones de AWS Encryption SDK para .NET. Puede configurarlo de forma explícita como práctica recomendada, pero no es necesario establecerlo. Sin embargo, si utiliza para.NET AWS Encryption SDK para descifrar el texto cifrado en otro idioma de la implementación AWS Encryption SDK sin compromiso clave, debe cambiar el valor de la política de compromiso a o. `REQUIRE_ENCRYPT_ALLOW_DECRYPT` `FORBID_ENCRYPT_ALLOW_DECRYPT` De lo contrario, el intento de descifrar el texto cifrado devolverá un error.
En el AWS Encryption SDK caso de.NET, se establece la política de compromiso en una instancia de. AWS Encryption SDK Cree una instancia de un `AwsEncryptionSdkConfig` objeto con un `CommitmentPolicy` parámetro y utilice el objeto de configuración para crear la AWS Encryption SDK instancia. A continuación, llama a los `Decrypt()` métodos `Encrypt()` y de la instancia configurada AWS Encryption SDK .
En este ejemplo, se establece la política de compromiso en `require-encrypt-allow-decrypt`.
```
// Instantiate the material providers
var materialProviders =
AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();
// Configure the commitment policy on the AWS Encryption SDK instance
var config = new AwsEncryptionSdkConfig
{
CommitmentPolicy = CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT
};
var encryptionSdk = AwsEncryptionSdkFactory.CreateAwsEncryptionSdk(config);
string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
var encryptionContext = new Dictionary()
{
{"purpose", "test"}encryptionSdk
};
var createKeyringInput = new CreateAwsKmsKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(),
KmsKeyId = keyArn
};
var keyring = materialProviders.CreateAwsKmsKeyring(createKeyringInput);
// Encrypt your plaintext data
var encryptInput = new EncryptInput
{
Plaintext = plaintext,
Keyring = keyring,
EncryptionContext = encryptionContext
};
var encryptOutput = encryptionSdk.Encrypt(encryptInput);
// Decrypt your ciphertext
var decryptInput = new DecryptInput
{
Ciphertext = ciphertext,
Keyring = keyring
};
var decryptOutput = encryptionSdk.Decrypt(decryptInput);
```
------
#### [ AWS Encryption CLI ]
Para establecer una política de compromiso en la CLI de AWS cifrado, utilice el `--commitment-policy` parámetro. Este parámetro se introduce en la versión 1.8.*x*.
En la última versión 1.*x*, cuando se utiliza el parámetro `--wrapping-keys` en un comando `--encrypt` o `--decrypt`, se requiere un parámetro `--commitment-policy` con el valor `forbid-encrypt-allow-decrypt`. De lo contrario, el parámetro `--commitment-policy` no es válido.
En las versiones 2.1.*x* y versiones posteriores, el parámetro `--commitment-policy` es opcional y tiene el valor predeterminado `require-encrypt-require-decrypt`, que no cifrará ni descifrará ningún texto cifrado sin el compromiso clave. Sin embargo, recomendamos establecer la política de compromiso de forma explícita en todas las llamadas de cifrado y descifrado para facilitar el mantenimiento y la solución de problemas.
En este ejemplo se establece la política de compromiso. También usa el parámetro `--wrapping-keys` que reemplaza al parámetro `--master-keys` que comienza en la versión 1.8.*x*. Para obtener más información, consulte [Actualización de los proveedores de claves AWS KMS maestras](migrate-mkps-v2.md). Para ver ejemplos completos, consulte [Ejemplos de la CLI AWS de cifrado](crypto-cli-examples.md).
```
\\ 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
\\ Encrypt your plaintext data - no change to algorithm suite used
$ aws-encryption-cli --encrypt \
--input hello.txt \
--wrapping-keys key=$keyArn \
--commitment-policy forbid-encrypt-allow-decrypt \
--metadata-output ~/metadata \
--encryption-context purpose=test \
--output .
\\ Decrypt your ciphertext - supports key commitment on 1.7 and later
$ aws-encryption-cli --decrypt \
--input hello.txt.encrypted \
--wrapping-keys key=$keyArn \
--commitment-policy forbid-encrypt-allow-decrypt \
--encryption-context purpose=test \
--metadata-output ~/metadata \
--output .
```
------
#### [ Java ]
A partir de la versión 1.7. *x* SDK de cifrado de AWS para Java, estableces la política de compromiso en tu instancia del `AwsCrypto` objeto que representa al AWS Encryption SDK cliente. Esta configuración de política de compromiso se aplica a todas las operaciones de cifrado y descifrado realizadas en ese cliente.
El `AwsCrypto()` constructor está en desuso en la última versión. *x* versiones de SDK de cifrado de AWS para Java y se elimina en la versión 2.0. *x*. Se sustituye por una nueva clase `Builder`, un método `Builder.withCommitmentPolicy()` y el tipo `CommitmentPolicy` enumerado.
En las últimas versiones 1.*x*, la clase `Builder` requiere el método `Builder.withCommitmentPolicy()` y el argumento `CommitmentPolicy.ForbidEncryptAllowDecrypt`. A partir de la versión 2.0.*x*, el método `Builder.withCommitmentPolicy()` es opcional; el valor predeterminado es `CommitmentPolicy.RequireEncryptRequireDecrypt`.
Para ver un ejemplo completo, consulte [SetCommitmentPolicyExample.java.](https://github.com/aws/aws-encryption-sdk-java/blob/master/src/examples/java/com/amazonaws/crypto/examples/v2/SetCommitmentPolicyExample.java)
```
// Instantiate the client
final AwsCrypto crypto = AwsCrypto.builder()
.withCommitmentPolicy(CommitmentPolicy.ForbidEncryptAllowDecrypt)
.build();
// Create a master key provider in strict mode
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder()
.buildStrict(awsKmsKey);
// Encrypt your plaintext data
CryptoResult encryptResult = crypto.encryptData(
masterKeyProvider,
sourcePlaintext,
encryptionContext);
byte[] ciphertext = encryptResult.getResult();
// Decrypt your ciphertext
CryptoResult decryptResult = crypto.decryptData(
masterKeyProvider,
ciphertext);
byte[] decrypted = decryptResult.getResult();
```
------
#### [ JavaScript ]
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 las últimas versiones 1.*x*, la función `buildClient` requiere el argumento `CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT`. A partir de la versión 2.0.*x*, el argumento de la política de compromiso es opcional y el valor predeterminado es `CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT`.
El código de Node.js y el navegador son idénticos para este propósito, excepto que el navegador necesita una declaración para establecer las credenciales.
En el siguiente ejemplo, se cifran los datos con un anillo de claves. AWS KMS La nueva función `buildClient` establece la política de compromiso en `FORBID_ENCRYPT_ALLOW_DECRYPT`, el valor predeterminado en las últimas versiones 1.*x*. Las funciones actualizadas `encrypt` y `decrypt` que `buildClient` devuelve hacen cumplir la política de compromiso que haya establecido.
```
import { buildClient } from '@aws-crypto/client-node'
const { encrypt, decrypt } = buildClient(CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT)
// Create an AWS KMS keyring
const generatorKeyId = 'arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias'
const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']
const keyring = new KmsKeyringNode({ generatorKeyId, keyIds })
// Encrypt your plaintext data
const { ciphertext } = await encrypt(keyring, plaintext, { encryptionContext: context })
// Decrypt your ciphertext
const { decrypted, messageHeader } = await decrypt(keyring, ciphertext)
```
------
#### [ Python ]
A partir de la versión 1.7. *x* SDK de cifrado de AWS para Python, estableces la política de compromiso en tu instancia de`EncryptionSDKClient`, un nuevo objeto que representa al AWS Encryption SDK cliente. La política de compromiso que establezca se aplica a todas las llamadas a `encrypt` y `decrypt` que usen esa instancia del cliente.
En las últimas versiones 1*x*, el constructor `EncryptionSDKClient` requiere el valor `CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT` enumerado. A partir de la versión 2.0.*x*, el argumento de la política de compromiso es opcional y el valor predeterminado es `CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT`.
En este ejemplo, se utiliza el nuevo constructor `EncryptionSDKClient` y se establece la política de compromiso en 1.7.*x* valor predeterminado. El constructor crea una instancia de un cliente que representa el AWS Encryption SDK. Cuando llama a los métodos `encrypt`, `decrypt` o `stream` de este cliente, estos aplican la política de compromiso que haya establecido. En este ejemplo también se utiliza el nuevo constructor de la `StrictAwsKmsMasterKeyProvider` clase, que especifica AWS KMS keys cuándo se cifra y se descifra.
Para ver un ejemplo completo, consulte [set\$1commitment.py.](https://github.com/aws/aws-encryption-sdk-python/blob/master/examples/src/legacy/set_commitment.py)
```
# Instantiate the client
client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT)
// Create a master key provider in strict mode
aws_kms_key = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
aws_kms_strict_master_key_provider = StrictAwsKmsMasterKeyProvider(
key_ids=[aws_kms_key]
)
# Encrypt your plaintext data
ciphertext, encrypt_header = client.encrypt(
source=source_plaintext,
encryption_context=encryption_context,
master_key_provider=aws_kms_strict_master_key_provider
)
# Decrypt your ciphertext
decrypted, decrypt_header = client.decrypt(
source=ciphertext,
master_key_provider=aws_kms_strict_master_key_provider
)
```
------
#### [ Rust ]
El `require-encrypt-require-decrypt` valor es la política de compromiso predeterminada en todas las versiones de Rust AWS Encryption SDK . Puede configurarlo de forma explícita como práctica recomendada, pero no es necesario establecerlo. Sin embargo, si utiliza la implementación AWS Encryption SDK de Rust AWS Encryption SDK sin compromiso de clave cifrada cifrada en otro idioma, tendrá que cambiar el valor de la política de compromiso a o. `REQUIRE_ENCRYPT_ALLOW_DECRYPT` `FORBID_ENCRYPT_ALLOW_DECRYPT` De lo contrario, el intento de descifrar el texto cifrado devolverá un error.
En el caso AWS Encryption SDK de Rust, se establece la política de compromiso en una instancia de. AWS Encryption SDK Cree una instancia de un `AwsEncryptionSdkConfig` objeto con un `comitment_policy` parámetro y utilice el objeto de configuración para crear la AWS Encryption SDK instancia. A continuación, llama a los `Decrypt()` métodos `Encrypt()` y de la instancia configurada AWS Encryption SDK .
En este ejemplo, se establece la política de compromiso en `forbid-encrypt-allow-decrypt`.
```
// Configure the commitment policy on the AWS Encryption SDK instance
let esdk_config = AwsEncryptionSdkConfig::builder()
.commitment_policy(ForbidEncryptAllowDecrypt)
.build()?;
let esdk_client = esdk_client::Client::from_conf(esdk_config)?;
// Create an AWS KMS client
let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
let kms_client = aws_sdk_kms::Client::new(&sdk_config);
// Create your encryption context
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()),
]);
// Instantiate the material providers library
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
// Create an AWS KMS keyring
let kms_keyring = mpl
.create_aws_kms_keyring()
.kms_key_id(kms_key_id)
.kms_client(kms_client)
.send()
.await?;
// Encrypt your plaintext data
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?;
// Decrypt your ciphertext
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?;
```
------
#### [ Go ]
```
import (
"context"
mpl "aws/aws-cryptographic-material-providers-library/releases/go/mpl/awscryptographymaterialproviderssmithygenerated"
mpltypes "aws/aws-cryptographic-material-providers-library/releases/go/mpl/awscryptographymaterialproviderssmithygeneratedtypes"
client "github.com/aws/aws-encryption-sdk/awscryptographyencryptionsdksmithygenerated"
esdktypes "github.com/aws/aws-encryption-sdk/awscryptographyencryptionsdksmithygeneratedtypes"
"github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/service/kms"
)
// Instantiate the AWS Encryption SDK client
commitPolicyForbidEncryptAllowDecrypt := mpltypes.ESDKCommitmentPolicyForbidEncryptAllowDecrypt
encryptionClient, err := client.NewClient(esdktypes.AwsEncryptionSdkConfig{CommitmentPolicy: &commitPolicyForbidEncryptAllowDecrypt})
if err != nil {
panic(err)
}
// Create an AWS KMS client
cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
panic(err)
}
kmsClient := kms.NewFromConfig(cfg, func(o *kms.Options) {
o.Region = KmsKeyRegion
})
// Optional: Create an encryption context
encryptionContext := map[string]string{
"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",
}
// Instantiate the material providers library
matProv, err := mpl.NewClient(mpltypes.MaterialProvidersConfig{})
if err != nil {
panic(err)
}
// Create an AWS KMS keyring
awsKmsKeyringInput := mpltypes.CreateAwsKmsKeyringInput{
KmsClient: kmsClient,
KmsKeyId: kmsKeyId,
}
awsKmsKeyring, err := matProv.CreateAwsKmsKeyring(context.Background(), awsKmsKeyringInput)
if err != nil {
panic(err)
}
// Encrypt your plaintext data
res, err := forbidEncryptClient.Encrypt(context.Background(), esdktypes.EncryptInput{
Plaintext: []byte(exampleText),
EncryptionContext: encryptionContext,
Keyring: awsKmsKeyring,
})
if err != nil {
panic(err)
}
// Decrypt your ciphertext
decryptOutput, err := forbidEncryptClient.Decrypt(context.Background(), esdktypes.DecryptInput{
Ciphertext: res.Ciphertext,
EncryptionContext: encryptionContext,
Keyring: awsKmsKeyring,
})
if err != nil {
panic(err)
}
```
------
# Solución de problemas de migración a las versiones más recientes
Antes de actualizar la aplicación a la versión 2.0. *x* o posterior del AWS Encryption SDK, actualice a la última versión 1. *x* versión de AWS Encryption SDK e impleméntela por completo. Esto le ayudará a evitar la mayoría de los errores que puedan producirse al actualizar a las versiones 2.0.*x* y versiones posteriores. Para obtener una guía detallada, incluidos ejemplos, consulte [Migrando su AWS Encryption SDK](migration.md).
**importante**
Verifique que su última versión 1.*x* es 1.7.*x* o una versión posterior de AWS Encryption SDK.
**nota**
**AWS CLI de cifrado**: referencias en esta guía a la versión 1.7. *x* de la AWS Encryption SDK se aplica a la versión 1.8. *x* de la CLI AWS de cifrado. Referencias en esta guía a la versión 2.0. *x* del AWS Encryption SDK se aplica a la 2.1. *x* de la CLI AWS de cifrado.
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.
Este tema está diseñado para ayudarlo a reconocer y resolver los errores más comunes que pueda encontrar.
**Topics**
+ [Objetos obsoletos o eliminados](#deprecated-removed)
+ [Conflicto de configuración: conjunto de políticas y algoritmos de compromiso](#configuration-conflict_1)
+ [Conflicto de configuración: política de compromiso y texto cifrado](#configuration-conflict_2)
+ [Falla en la validación del compromiso clave](#commitment-failed)
+ [Otras fallas de cifrado](#encrypt-failed)
+ [Otras fallas de descifrado](#decrypt-failed)
+ [Consideraciones de restauración](#migration-rollback)
## Objetos obsoletos o eliminados
Versión 2.0.*x* incluye varios cambios importantes, como la eliminación de constructores, métodos, funciones y clases antiguos que estaban en desuso en la versión 1.7.*x*. Para evitar errores del compilador, errores de importación, errores de sintaxis y errores de símbolos no encontrados (según el lenguaje de programación), actualice primero a la última versión. *x* versión de la AWS Encryption SDK para su lenguaje de programación. (La versión debe ser 1.7.*x* o posterior). Mientras usa la última versión 1.*x*, puede empezar a utilizar los elementos de reemplazo antes de eliminar los símbolos originales.
Si necesita actualizar a la versión 2.0.*x* o posterior inmediatamente, [consulte el registro de cambios](about-versions.md) de su lenguaje de programación y sustituya los símbolos antiguos por los símbolos recomendados en el registro de cambios.
## Conflicto de configuración: conjunto de políticas y algoritmos de compromiso
Si especifica un conjunto de algoritmos que entra en conflicto con su [política de compromiso](concepts.md#commitment-policy), la llamada al cifrado fallará y aparecerá un error de *conflicto de configuración*.
Para evitar este tipo de error, no especifique un conjunto de algoritmos. De forma predeterminada, AWS Encryption SDK elige el algoritmo más seguro que sea compatible con su política de compromiso. Sin embargo, si debe especificar un conjunto de algoritmos, por ejemplo, uno sin firmar, asegúrese de elegir un conjunto de algoritmos que sea compatible con su política de compromiso.
| Política de compromiso | Compatibilidad con los conjuntos de algoritmos |
| --- | --- |
| ForbidEncryptAllowDecrypt | Cualquier conjunto de algoritmos *sin* compromiso clave, como:AES\$1256\$1GCM\$1IV12\$1TAG16\$1HKDF\$1SHA384\$1ECDSA\$1P384([03 78](algorithms-reference.md)) (con firma) `AES_256_GCM_IV12_TAG16_HKDF_SHA256`([01 78](algorithms-reference.md)) (sin firma) |
| RequireEncryptAllowDecryptRequireEncryptRequireDecrypt | Cualquier conjunto de algoritmos *con* un compromiso clave, como:AES\$1256\$1GCM\$1HKDF\$1SHA512\$1COMMIT\$1KEY\$1ECDSA\$1P384([05 78](algorithms-reference.md)) (con firma) `AES_256_GCM_HKDF_SHA512_COMMIT_KEY`([04 78](algorithms-reference.md)) (sin firma) |
Si encuentra este error cuando no ha especificado un conjunto de algoritmos, es posible que su [administrador de materiales criptográficos](concepts.md#crypt-materials-manager) (CMM) haya elegido el conjunto de algoritmos conflictivo. El CMM predeterminado no seleccionará un conjunto de algoritmos conflictivo, pero sí un CMM personalizado. Para obtener ayuda, consulte la documentación de su CMM personalizado.
## Conflicto de configuración: política de compromiso y texto cifrado
La [política de compromiso](concepts.md#commitment-policy) de `RequireEncryptRequireDecrypt` no permite a AWS Encryption SDK descifrar un mensaje que se haya cifrado sin el [compromiso clave](concepts.md#key-commitment). Si le pide que descifre un mensaje sin confirmar la clave, devolverá un error de *conflicto de configuración*. AWS Encryption SDK
Para evitar este error, antes de establecer la política de compromiso de `RequireEncryptRequireDecrypt`, asegúrese de que todos los textos cifrados sin compromiso clave se descifren y se vuelvan a cifrar con compromiso clave, o de que sean gestionados por otra aplicación. Si se produce este error, puede arrojar un error para el texto cifrado conflictivo o cambiar temporalmente la política de compromiso a `RequireEncryptAllowDecrypt`.
Si se produce este error porque actualizó a la versión 2.0.*x* o posterior desde una versión anterior a la 1.7.*x* sin actualizar primero a la última versión 1.*x* (versión 1.7.*x* o posterior), considere la posibilidad [de volver](#migration-rollback) a la última versión 1.*x* e implementar esa versión en todos los hosts antes de actualizar a la versión 2.0.*x* o posterior. Para obtener ayuda, consulte [¿Cómo migrar e implementar el AWS Encryption SDK](migration-guide.md).
## Falla en la validación del compromiso clave
Al descifrar los mensajes cifrados con un compromiso clave, es posible que aparezca un mensaje de *error en la validación del compromiso clave*. Esto indica que la llamada de descifrado ha fallado porque la clave de datos de un [mensaje cifrado](concepts.md#DEK) no es idéntica a la clave de datos única del mensaje. Al validar la clave de datos durante el descifrado, el [compromiso clave](concepts.md#key-commitment) evita que se descodifique un mensaje que pueda tener como resultado más de un texto no cifrado.
Este error indica que el mensaje cifrado que estaba intentando descifrar no fue devuelto por el AWS Encryption SDK. Puede ser un mensaje creado manualmente o el resultado de una corrupción de datos. Si se produce este error, la aplicación puede rechazar el mensaje y continuar o dejar de procesar los mensajes nuevos.
## Otras fallas de cifrado
El cifrado puede fallar por varios motivos. No puede utilizar un conjunto de [claves de detección de AWS KMS](use-kms-keyring.md#kms-keyring-discovery) ni un [proveedor de claves maestras en el modo de detección](migrate-mkps-v2.md) para cifrar un mensaje.
Asegúrese de especificar un conjunto de claves o un proveedor de claves maestras con claves de encapsulamiento que tenga [permiso para usar para](use-kms-keyring.md#kms-keyring-permissions) el cifrado. Para obtener ayuda sobre los permisos AWS KMS keys, consulte [Visualización de una política clave](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-viewing.html) y [Determinación del acceso a una AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/determining-access.html) en la *Guía para AWS Key Management Service desarrolladores*.
## Otras fallas de descifrado
Si se produce un error al intentar descifrar un mensaje cifrado, significa que AWS Encryption SDK no ha podido (o no quiere) descifrar ninguna de las claves de datos cifrados del mensaje.
Si ha utilizado un conjunto de claves o un proveedor de claves maestras que especifique las claves de empaquetado, AWS Encryption SDK utilizará únicamente las claves de empaquetado que especifique. Compruebe que está utilizando las claves de encapsulamiento que desea utilizar y que tiene `kms:Decrypt` permiso para utilizar al menos una de las claves de encapsulamiento. Si lo utiliza AWS KMS keys, como alternativa, puede intentar descifrar el mensaje con un [anillo de claves de AWS KMS detección o un proveedor de claves](use-kms-keyring.md#kms-keyring-discovery) [maestras](migrate-mkps-v2.md) en modo de detección. Si la operación se realiza correctamente, antes de devolver el texto no cifrado, compruebe que la clave utilizada para descifrar el mensaje es de confianza.
## Consideraciones de restauración
Si su aplicación no logra cifrar o descifrar los datos, normalmente puede resolver el problema actualizando los símbolos de código, los conjuntos de claves, los proveedores de claves maestras o la [política de compromiso](concepts.md#commitment-policy). Sin embargo, en algunos casos, puede que decidas que es mejor revertir la aplicación a una versión anterior de AWS Encryption SDK.
Si tiene que revertirla, hágalo con precaución. Versiones anteriores a la 1.7 AWS Encryption SDK . *x* [no puede descifrar el texto cifrado con un compromiso de clave.](concepts.md#key-commitment)
+ Retroceder desde la última versión 1.*x* a una versión anterior de la AWS Encryption SDK es generalmente seguro. Puede que tenga que deshacer los cambios realizados en el código para utilizar símbolos y objetos que no son compatibles con las versiones anteriores.
+ Una vez que haya empezado a cifrar con un compromiso clave (estableciendo su política de compromiso en `RequireEncryptAllowDecrypt`) en la versión 2.0.*x* o posterior, puede volver a la versión 1.7.*x*, pero no a una versión anterior. Versiones anteriores a la 1.7 AWS Encryption SDK . *x* [no puede descifrar el texto cifrado con un compromiso de clave.](concepts.md#key-commitment)
Si habilita accidentalmente el cifrado con compromiso clave antes de que todos los hosts puedan descifrar con compromiso clave, sería mejor continuar con la implementación en lugar de revertirla. Si los mensajes son transitorios o se pueden eliminar de forma segura, podría considerar la posibilidad de revertirlos con la pérdida de mensajes. Si es necesaria una reversión, podría considerar la posibilidad de crear una herramienta que descifre y vuelva a cifrar todos los mensajes.