Requisitos previos Instalación Llaveros AWS KMS Contexto de cifrado obligatorio (CMM)

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 más información sobre la programación conSDK de cifrado de AWS para Java, consulte el aws-encryption-sdk-javarepositorio en GitHub. Para obtener documentación de la API, consulte la documentación de Javadoc para SDK de cifrado de AWS para Java.

Requisitos previos

Antes de instalar el SDK de cifrado de AWS para Java, asegúrese de que cumpla 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 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).

Bouncy Castle

SDK de cifrado de AWS para Java requiere Bouncy Castle.

Las versiones 1.6.1 y posteriores del SDK de cifrado de AWS para Java usan Bouncy Castle para serializar y deserializar objetos criptográficos. Puede utilizar Bouncy Castle o Bouncy Castle FIPS para cumplir este requisito. Para obtener ayuda para instalar y configurar Bouncy Castle FIPS, consulte la documentación de BC FIPS, especialmente las guías de usuario y los archivos PDF de política de seguridad.
Las versiones anteriores de SDK de cifrado de AWS para Java usan 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 dispone de Bouncy Castle, vaya a las últimas versiones de Bouncy Castle para descargar el archivo de proveedor que corresponda a su JDK. También puedes usar Apache Maven para obtener el artefacto para el proveedor estándar de Bouncy Castle (bcprov-ext-jdk15on) o el artefacto para Bouncy Castle FIPS (bc-fips).

AWS SDK for Java

Versión 3. x de los SDK de cifrado de AWS para Java requiere elAWS SDK for Java 2.x, incluso si no usas AWS KMS llaveros.

Versión 2. x o una versión anterior de la SDK de cifrado de AWS para Java no requiere laAWS SDK for Java. Sin embargo, el AWS SDK for Java es necesario para usar AWS Key Management Service (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 for Java AWS Encryption SDKel código AWS SDK for Java 1.x y 2.x es interoperable. Por ejemplo, puede cifrar los datos con un AWS Encryption SDK código compatible con la versión AWS SDK for 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 for Java Para obtener más información sobre cómo actualizar su versión de AWS Encryption SDK, consulte Migración de su AWS Encryption SDK.

Al actualizar el código del SDK de cifrado de AWS para Java del AWS SDK for Java 1.x a AWS SDK for Java 2.x, sustituya las referencias a la interfaz de AWSKMS en el AWS SDK for Java 1.x por las referencias a la interfaz de KmsClient en el AWS SDK for Java 2.x. El SDK de cifrado de AWS para Java no es compatible con la interfaz de KmsAsyncClient. Además, actualice el código para usar los objetos relacionados al AWS KMS en el espacio de nombres kmssdkv2, en lugar del espacio de nombres kms.

Para instalar AWS SDK for Java, use Apache Maven.

Para importar todo AWS SDK for Java como una dependencia declárelo en el archivo pom.xml.
Para crear una dependencia solo para el módulo AWS KMS en AWS SDK for Java 1.x, siga las instrucciones para especificar módulos concretos y establezca el artifactId en aws-java-sdk-kms.
Para crear una dependencia solo para el módulo AWS KMS en AWS SDK for Java 2.x, siga las instrucciones para especificar módulos concretos. Establezca el groupId a software.amazon.awssdk y el artifactId a kms.

Para ver más cambios, consulte las diferencias entre la versión AWS SDK for Java 1.x y la 2.x en la Guía para AWS SDK for Java 2.x 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 están en end-of-supportfase.

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, se introdujeron nuevas funciones de seguridad en la versión 2.0x, que 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 más información, consulte Migrar su AWS Encryption SDK.

Puede instalar el SDK de cifrado de AWS para Java de una de las siguientes maneras:

Manualmente

Para instalar el repositorioSDK de cifrado de AWS para Java, clone o descargue el aws-encryption-sdk-java GitHubrepositorio.

Con Apache Maven

El SDK de cifrado de AWS para Java está disponible a través de Apache Maven con la siguiente definición de dependencias.


<dependency>
  <groupId>com.amazonaws</groupId>
  <artifactId>aws-encryption-sdk-java</artifactId>
  <version>3.0.0</version>
</dependency>

Después de instalar el SDK, comience consultando el ejemplo de código Java de esta guía y el Javadoc en el resto. GitHub

AWS KMSllaveros en el SDK de cifrado de AWS para Java

Versión 3. x de los SDK de cifrado de AWS para Java utiliza anillos de claves para realizar el cifrado de sobres. Los AWS KMS anillos de claves básicos solo SDK de cifrado de AWS para Java requieren una clave KMS. También requieren un cliente de AWS KMS, lo que le da la oportunidad de configurar el cliente para Región de AWS de la clave KMS.

Para crear un llavero de AWS KMS con una o más claves de empaquetado, utilice un llavero múltiple. SDK de cifrado de AWS para JavaTiene un llavero especial con varios llaveros que admite una o más AWS KMS teclas y un llavero estándar con varios llaveros de cualquier tipo compatible. Algunos programadores prefieren usar un método de llaveros múltiples para crear todos sus llaveros, y este método apoya esa estrategia. SDK de cifrado de AWS para Java

SDK de cifrado de AWS para JavaProporciona llaveros básicos de una sola tecla y varios llaveros para todos los casos de uso típicos, incluidas las claves multirregionales. AWS KMS

Por ejemplo, para crear un AWS KMS llavero con una sola AWS KMS tecla, puede utilizar el método]. CreateAwsKmsKeyring()


// Instantiate the AWS Encryption SDK and material providers
final AwsCrypto crypto = AwsCrypto.builder().build();
final MaterialProviders materialProviders = MaterialProviders.builder()
        .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
        .build();

// Create the keyring
CreateAwsKmsKeyringInput kmsKeyringInput = CreateAwsKmsKeyringInput.builder()
        .kmsKeyId(keyArn)
        .kmsClient(KmsClient.create())
        .build();
IKeyring kmsKeyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);

Para crear un llavero con una o más claves de AWS KMS, utilice el método CreateAwsKmsMultiKeyring(). En este ejemplo, se utilizan dos claves KMS. Para especificar una clave KMS, utilice solo el parámetro generator. El parámetro msKeyIds que especifica claves KMS adicionales es opcional.

La entrada de este llavero no requiere un cliente de AWS KMS. En su lugar, AWS Encryption SDK utiliza el cliente de AWS KMS predeterminado para cada región representado por una clave KMS en el llavero. Por ejemplo, si la clave KMS identificada por el valor del parámetro Generator se encuentra en la región Oeste de EE. UU. (Oregón) (us-west-2), la AWS Encryption SDK crea un cliente de AWS KMS predeterminado para la región us-west-2. Si necesita personalizar el cliente de AWS KMS, utilice el método CreateAwsKmsKeyring().


// Instantiate the AWS Encryption SDK and material providers
final AwsCrypto crypto = AwsCrypto.builder().build();
final MaterialProviders materialProviders = MaterialProviders.builder()
            .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
            .build();

String generatorKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
List<String> additionalKey = Collections.singletonList("arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321");
// Create the keyring
final CreateAwsKmsMultiKeyringInput keyringInput = CreateAwsKmsMultiKeyringInput.builder()
        .generator(generatorKey)
        .kmsKeyIds(additionalKey)
        .build();
final IKeyring kmsKeyring = matProv.CreateAwsKmsMultiKeyring(keyringInput);

SDK de cifrado de AWS para Javaadmite conjuntos de AWS KMS claves que utilizan cifrado simétrico (SYMMETRIC_DEFAULT) o claves RSA KMS asimétricas. AWS KMSlos llaveros creados con claves asimétricas de RSA KMS solo pueden contener un par de claves.

Para cifrar con un AWS KMS anillo de claves RSA asimétrico, no necesita kms: GenerateDataKey ni KMS:Encrypt porque debe especificar el material de clave pública que quiere usar para el cifrado al crear el anillo de claves. No se realizan llamadas a AWS KMS al cifrar con este llavero. Para descifrar con un llavero RSA asimétrico de AWS KMS, necesita el permiso kms:Decrypt.

Para crear un llavero RSA asimétrico de AWS KMS, debe proporcionar la clave pública y el ARN de clave privada de su clave RSA KMS asimétrica. La clave pública debe estar codificada con PEM. En el ejemplo siguiente se crea un llavero de AWS KMS con un par de claves RSA asimétricas.


// Instantiate the AWS Encryption SDK and material providers
final AwsCrypto crypto = AwsCrypto.builder()
        // Specify algorithmSuite without asymmetric signing here
        //
        // ALG_AES_128_GCM_IV12_TAG16_NO_KDF("0x0014"),
        // ALG_AES_192_GCM_IV12_TAG16_NO_KDF("0x0046"),
        // ALG_AES_256_GCM_IV12_TAG16_NO_KDF("0x0078"),
        // ALG_AES_128_GCM_IV12_TAG16_HKDF_SHA256("0x0114"),
        // ALG_AES_192_GCM_IV12_TAG16_HKDF_SHA256("0x0146"),
        // ALG_AES_256_GCM_IV12_TAG16_HKDF_SHA256("0x0178")
        .withEncryptionAlgorithm(CryptoAlgorithm.ALG_AES_256_GCM_IV12_TAG16_HKDF_SHA256)
        .build();
                
final MaterialProviders matProv = MaterialProviders.builder()
        .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
        .build();

// Create a KMS RSA keyring.
//    This keyring takes in:
//     - kmsClient
//     - kmsKeyId: Must be an ARN representing an asymmetric RSA KMS key
//     - publicKey: A ByteBuffer of a UTF-8 encoded PEM file representing the public
//                  key for the key passed into kmsKeyId
//     - encryptionAlgorithm: Must be either RSAES_OAEP_SHA_256 or RSAES_OAEP_SHA_1
final CreateAwsKmsRsaKeyringInput createAwsKmsRsaKeyringInput =
        CreateAwsKmsRsaKeyringInput.builder()
                .kmsClient(KmsClient.create())
                .kmsKeyId(rsaKeyArn)
                .publicKey(publicKey)
                .encryptionAlgorithm(EncryptionAlgorithmSpec.RSAES_OAEP_SHA_256)
                .build();
IKeyring awsKmsRsaKeyring = matProv.CreateAwsKmsRsaKeyring(createAwsKmsRsaKeyringInput);

Contextos de cifrado necesarios en la versión 3.x

Con la versión 3. x deSDK de cifrado de AWS para Java, puede utilizar el contexto de cifrado CMM requerido para requerir los contextos de cifrado en sus operaciones criptográficas. Un contexto de cifrado es un conjunto de pares de clave-valor no secretos. El contexto de cifrado se vincula criptográficamente a los datos cifrados, de tal forma que se requiere el mismo contexto de cifrado para descifrar los datos. Cuando utiliza el contexto de cifrado CMM requerido, puede especificar una o más claves de contexto de cifrado obligatorias (claves obligatorias) que deben incluirse en todas las llamadas de cifrado y descifrado.

nota

El contexto de cifrado requerido, CMM, solo es interoperable con la versión 4. x del AWS Encryption SDK para .NET. No es interoperable con ninguna otra implementación de lenguaje de programación. Si cifra los datos mediante el contexto de cifrado CMM requerido, solo podrá descifrarlos con la versión 3. x de la SDK de cifrado de AWS para Java o la versión 4. x de AWS Encryption SDK para .NET.

Al cifrar, la AWS Encryption SDK comprueba que todas las claves de contexto de cifrado necesarias estén incluidas en el contexto de cifrado que especificó. La AWS Encryption SDK firma los contextos de cifrado que especificó. Solo los pares clave-valor que no son claves obligatorias se serializan y almacenan en texto no cifrado en el encabezado del mensaje cifrado que devuelve la operación de cifrado.

Al descifrar, debe proporcionar un contexto de cifrado que contenga todos los pares clave-valor que representan las claves necesarias. La AWS Encryption SDK utiliza este contexto de cifrado y los pares clave-valor almacenados en el encabezado del mensaje cifrado para reconstruir el contexto de cifrado original que especificó en la operación de cifrado. Si la AWS Encryption SDK no puede reconstruir el contexto de cifrado original, se produce un error en la operación de descifrado. Si proporciona un par clave-valor que contiene la clave requerida con un valor incorrecto, el mensaje cifrado no se puede descifrar. Debe proporcionar el mismo par clave-valor que se especificó al cifrar.

importante

Considere detenidamente qué valores elige para las claves requeridas en su contexto de cifrado. Debe poder volver a proporcionar las mismas claves y sus valores correspondientes al descifrar. Si no puede reproducir las claves requeridas, el mensaje cifrado no se podrá descifrar.

El siguiente ejemplo inicializa un llavero de AWS KMS con el contexto de cifrado CMM obligatorio.


// Instantiate the AWS Encryption SDK
final AwsCrypto crypto = AwsCrypto.builder()
        .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
        .build();
    
// Create your encryption context
final Map<String, String> encryptionContext = new HashMap<>();
encryptionContext.put("encryption", "context");
encryptionContext.put("is not", "secret");
encryptionContext.put("but adds", "useful metadata");
encryptionContext.put("that can help you", "be confident that");
encryptionContext.put("the data you are handling", "is what you think it is");    

// Create a list of required encryption contexts
final List<String> requiredEncryptionContextKeys = Arrays.asList("encryption", "context");
    
// Create the keyring
final MaterialProviders materialProviders = MaterialProviders.builder()
        .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
        .build();
final CreateAwsKmsKeyringInput keyringInput = CreateAwsKmsKeyringInput.builder()
        .kmsKeyId(keyArn)
        .kmsClient(KmsClient.create())
        .build();
IKeyring kmsKeyring = materialProviders.CreateAwsKmsKeyring(keyringInput);
    
// Create the required encryption context CMM
ICryptographicMaterialsManager cmm = 
    materialProviders.CreateDefaultCryptographicMaterialsManager(
        CreateDefaultCryptographicMaterialsManagerInput.builder()
            .keyring(kmsKeyring)
            .build()
    );
ICryptographicMaterialsManager requiredCMM = 
    materialProviders.CreateRequiredEncryptionContextCMM(
        CreateRequiredEncryptionContextCMMInput.builder()
            .requiredEncryptionContextKeys(requiredEncryptionContextKeys)
            .underlyingCMM(cmm)
            .build()
        );

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Ejemplos