Actualización de los proveedores de claves maestras AWS KMS

Para migrar a la última versión 1.x de AWS Encryption SDK, y 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 detección. 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, el SDK de cifrado de AWS para Python, y la CLI de cifrado de AWS. Los ejemplos de esta sección le mostrarán cómo actualizar el código.

nota

En Python, active las advertencias de obsolescencia. Esto te ayudará a identificar las partes del código que necesita actualizar.

Si utiliza una clave maestra AWS KMS (no un proveedor de claves maestras), puede saltarse este paso. Las claves maestras AWS KMS no están en desuso ni se han eliminado. Solo cifran y descifran con las claves de encapsulación 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, consulte la sección Ejemplos del repositorio de GitHub correspondiente a su lenguaje de programación. Además, estos ejemplos suelen utilizar ARN de clave para representar AWS KMS keys. Al crear un proveedor de claves maestras para el cifrado, puede utilizar cualquier identificador de AWS KMS clave 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 usuarios de AWS Encryption SDK, infórmese sobre cómo establecer su política de compromiso Establecer su política de compromiso.

Para los usuarios de SDK de cifrado de AWS para C y SDK de cifrado de AWS para JavaScript, infórmese sobre una actualización opcional de los conjuntos de claves en Actualización de los conjuntos de clave AWS KMS.

Migración al modo estricto

Después de actualizar a la última versión 1.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 encapsulación que se utilizarán al cifrar y descifrar. El AWS Encryption SDK utiliza únicamente las claves de encapsulación 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 Cuentas de AWS y regiones.

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.

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 encapsulación.

// 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, consulte 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 solo el AWS KMS key que usted especifique.

# 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_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 versión 1.1.7 o anterior de la CLI de cifrado de AWS.

En la versión 1.1.7 y anteriores, al cifrar, se especifican una o más claves maestras (o claves de encapsulación), como una AWS KMS key. Al descifrar, no puede especificar ninguna clave de encapsulación a menos que utilice un proveedor de claves maestras personalizado. La CLI de cifrado de AWS puede usar cualquier clave de encapsulación 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.x o posterior de la CLI de cifrado de AWS. Para ver ejemplos completos, consulteEjemplos de la CLI de cifrado del AWS.

El --master-keys parámetro 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 encapsulación deseada.

Para actualizar al modo estricto, utilice el atributo clave del --wrapping-keys parámetro para especificar una clave de encapsulación 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 modo estricto para los proveedores de claves AWS KMS maestras, es decir, especificar las claves de encapsulación al cifrar y descifrar. Siempre debe especificar las claves de encapsulación al cifrar. Sin embargo, hay situaciones en las que no es práctico especificar los ARN de clave de AWS KMS keys para el descifrado. Por ejemplo, si utiliza alias para identificar el AWS KMS keys al cifrar, pierde la ventaja de los alias si tiene que enumerar los ARN de clave al descifrar. 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 encapsulación, por lo que no puede utilizarlas para cifrar. Al descifrar, pueden usar cualquier clave de encapsulación 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 en Referencia general de AWS.

Los siguientes ejemplos crean 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 encapsulación 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.

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 método Builder.buildDiscovery() utiliza una DiscoveryFilter que limita la cantidad AWS Encryption SDK a AWS KMS keys en la partición y las cuentas especificadas de AWS.

// 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_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 detección para el descifrado, utiliza DiscoveryAwsKmsMasterKeyProvider una DiscoveryFilter que limita la cantidad AWS Encryption SDK a 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.x o posterior de la CLI de cifrado de AWS. A partir de la versión 1.7.x, el --wrapping-keys parámetro es obligatorio para cifrar y descifrar. El --wrapping-keys parámetro admite el modo estricto y el modo de detección. Para ver ejemplos completos, consulteEjemplos de la CLI de cifrado del AWS.

Al cifrar, en este ejemplo se especifica una clave de encapsulación, que es obligatoria. Al descifrar, elige explícitamente el modo de detección mediante el discovery atributo del --wrapping-keys parámetro con un valor de true.

Para limitar las claves de encapsulación que AWS Encryption SDK puede usar en el modo de detección a aquellas Cuentas de AWS en particular, en este ejemplo se utilizan los atributos discovery-partition y discovery-account del parámetro --wrapping-keys. 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 .