Pré-requisitos Instalação Tokens de autenticação do AWS KMS CMM do contexto de criptografia necessário

AWS Encryption SDK for Java

Este tópico explica como instalar e usar o AWS Encryption SDK for Java. Para obter detalhes sobre a programação com oAWS Encryption SDK for Java, consulte o aws-encryption-sdk-javarepositório em GitHub. Para obter a documentação da API, consulte o Javadoc para AWS Encryption SDK for Java.

Tópicos

Pré-requisitos
Instalação
Tokens de autenticação do AWS KMS
CMM do contexto de criptografia necessário
Exemplos

Pré-requisitos

Antes de instalar o AWS Encryption SDK for Java, verifique se você tem os pré-requisitos a seguir.

Um ambiente de desenvolvimento Java

Você precisará do Java 8 ou posterior. No site da Oracle, acesse Java SE Downloads e faça download e instale o Java SE Development Kit (JDK).

Se você usa o Oracle JDK, também precisara fazer download e instalar os arquivos de política de jurisdição de força ilimitada JCE (Java Cryptography Extension).

Bouncy Castle

O AWS Encryption SDK for Java requer o Bouncy Castle.

O AWS Encryption SDK for Java versões 1.6.1 e posteriores usam Bouncy Castle para serializar e desserializar objetos de criptografia. Você pode usar o Bouncy Castle ou o Bouncy Castle FIPS para atender a esse requisito. Para obter ajuda para instalar e configurar o Bouncy Castle FIPS, consulte a Documentação do BC FIPS, especialmente os Guias do usuário e os PDFs de Política de segurança .
Versões anteriores do AWS Encryption SDK for Java usam a API de criptografia do Bouncy Castle para Java. Este requisito só é atendido por não FIPS Bouncy Castle.

Se você não tiver o Bouncy Castle, visite o Bouncy Castle latest releases para fazer download do arquivo do provedor que corresponde a seu JDK. Você também pode usar o Apache Maven para obter o artefato para o provedor padrão do Bouncy Castle (bcprov-ext-jdk15on) ou o artefato para o Bouncy Castle FIPS (bc-fips).

AWS SDK for Java

Versão 3. x of the AWS Encryption SDK for Java requer oAWS SDK for Java 2.x, mesmo se você não usar AWS KMS chaveiros.

Versão 2. x ou anterior do AWS Encryption SDK for Java não requer AWS SDK for Java o. No entanto, o AWS SDK for Java é necessário para usar o AWS Key Management Service (AWS KMS) como provedor de chave mestra. A partir da versão 2.4.0 do AWS Encryption SDK for Java, o AWS Encryption SDK for Java é compatível com as versões 1.x e 2.x do AWS SDK for Java. os códigos do AWS Encryption SDK para o AWS SDK for Java versões 1.x e 2.x são interoperáveis. Por exemplo, você pode criptografar dados com um código AWS Encryption SDK compatível com o AWS SDK for Java 1.x e descriptografá-los usando um código compatível com o AWS SDK for Java 2.x (ou vice-versa). As versões do AWS Encryption SDK for Java anteriores à 2.4.0 somente são compatíveis com o AWS SDK for Java 1.x. Para obter mais informações sobre a atualização da sua versão do AWS Encryption SDK, consulte Como migrar seu AWS Encryption SDK.

Ao atualizar seu código do AWS Encryption SDK for Java de AWS SDK for Java 1.x para AWS SDK for Java 2.x, substitua as referências à interface AWSKMS no AWS SDK for Java 1.x por referências à interface KmsClient no AWS SDK for Java 2.x. O AWS Encryption SDK for Java não é compatível com a interface KmsAsyncClient. Além disso, atualize seu código para usar os objetos relacionados ao AWS KMS no namespace kmssdkv2, em vez do namespace kms.

Para instalar o AWS SDK for Java, use o Apache Maven.

Para importar todo o AWS SDK for Java como uma dependência, declare-o no arquivo pom.xml.
Para criar uma dependência somente para o módulo AWS KMS no AWS SDK for Java 1.x, siga as instruções para especificar módulos específicos, e defina o artifactId como aws-java-sdk-kms.
Para criar uma dependência somente para o módulo AWS KMSno AWS SDK for Java 2.x, siga as instruções para especificar módulos específicos. Defina o groupId como software.amazon.awssdk e artifactId como kms.

Para ver mais mudanças, consulte Qual a diferença entre a versão 1.x e a 2.x do AWS SDK for Java no Guia do Desenvolvedor do AWS SDK for Java 2.x.

Os exemplos de Java no Guia do Desenvolvedor do AWS Encryption SDK usam o AWS SDK for Java 2.x.

Instalação

Instalar a versão mais recente do AWS Encryption SDK for Java.

nota

Todas as versões AWS Encryption SDK for Java anteriores à 2.0.0 estão em end-of-supportfase.

Você pode atualizar com segurança a partir da versão 2.0.x e posteriores até a versão mais recente do AWS Encryption SDK for Java sem realizar alterações no código ou nos dados. No entanto, os novos atributos de segurança introduzidos na versão 2.0.x não são compatíveis com versões anteriores. Para atualizar a partir de versões anteriores à 1.7.x até a versão 2.0. x e posteriores, primeiro será necessário atualizar para a versão 1.x mais recente doAWS Encryption SDK. Para obter detalhes, consulte Como migrar seu AWS Encryption SDK.

É possível instalar o AWS Encryption SDK for Java das seguintes maneiras.

Manualmente

Para instalar oAWS Encryption SDK for Java, clone ou baixe o aws-encryption-sdk-java GitHubrepositório.

Uso do Apache Maven

O AWS Encryption SDK for Java está disponível por meio do Apache Maven com a definição de dependência a seguir.


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

Depois de instalar o SDK, comece examinando o exemplo de código Java neste guia e o Javadoc ativado. GitHub

AWS KMSchaveiros no AWS Encryption SDK for Java

Versão 3. x do AWS Encryption SDK for Java usa chaveiros para realizar a criptografia de envelopes. Os AWS KMS chaveiros básicos do pacote AWS Encryption SDK for Java levam apenas uma chave KMS. Eles também exigem um cliente do AWS KMS, o que dá a você a oportunidade de configurar o cliente para a Região da AWS da chave KMS.

Para criar um token de autenticação do AWS KMS com uma ou mais chaves de encapsulamento, use um multitoken de autenticação. AWS Encryption SDK for JavaTem um porta-chaves especial que aceita uma ou mais AWS KMS teclas e um porta-chaves padrão que aceita um ou mais chaveiros de qualquer tipo compatível. Alguns programadores preferem usar um método de vários chaveiros para criar todos os seus chaveiros, e ele apóia essa estratégia. AWS Encryption SDK for Java

AWS Encryption SDK for JavaEle fornece chaveiros básicos de chave única e chaveiros múltiplos para todos os casos de uso típicos, incluindo chaves multirregionais. AWS KMS

Por exemplo, para criar um AWS KMS chaveiro com uma AWS KMS chave, você pode usar o métodoCreateAwsKmsKeyring()].


// 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 criar um token de autenticação com uma ou mais chaves do AWS KMS, use o método CreateAwsKmsMultiKeyring(). Este exemplo usa duas chaves KMS. Para especificar uma chave do KMS, use o parâmetro generator. O parâmetro msKeyIds, que especifica chaves KMS adicionais, é opcional.

A entrada para este token de autenticação não requer um cliente do AWS KMS. Em vez disso, o AWS Encryption SDK usa o cliente do AWS KMS padrão para cada região representada por uma chave do KMS no token de autenticação. Por exemplo, se a chave KMS identificada pelo valor do parâmetro Generator estiver na região Oeste dos EUA (Oregon) (us-west-2), o AWS Encryption SDK criará um cliente do AWS KMS padrão para a região us-west-2. Se você precisar personalizar o cliente do AWS KMS, use o 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);

AWS Encryption SDK for Javasuporta AWS KMS chaveiros que usam criptografia simétrica (SYMMETRIC_DEFAULT) ou chaves RSA KMS assimétricas. AWS KMSchaveiros criados com chaves RSA KMS assimétricas só podem conter um par de chaves.

Para criptografar com um AWS KMS chaveiro RSA assimétrico, você não precisa de kms: GenerateDataKey ou kms:Encrypt porque você deve especificar o material de chave pública que deseja usar para criptografia ao criar o chaveiro. Nenhuma chamada do AWS KMS é feita ao criptografar com este token de autenticação. Para descriptografar com um token de autenticação de RSA assimétrico do AWS KMS, é necessária a permissão KMS:Decrypt.

Para criar um token de autenticação de RSA assimétrico do AWS KMS, você deve fornecer o ARN de chave pública e de chave privada da sua chave RSA assimétrica do KMS. A chave pública deve ser codificada em PEM. O exemplo a seguir cria um token de autenticação do AWS KMS com um par de chaves RSA assimé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 criptografia necessários na versão 3.x

Com a versão 3. x doAWS Encryption SDK for Java, você pode usar o contexto de criptografia necessário CMM para exigir contextos de criptografia em suas operações criptográficas. Um contexto de criptografia é um conjunto de pares de chave/valor não secretos. O contexto de criptografia é associado de maneira criptográfica aos dados criptografados de forma que o mesmo contexto de criptografia é necessário para descriptografar o campo. Ao usar o CMM de contexto de criptografia necessário, é possível especificar uma ou mais chaves de contexto de criptografia necessárias (chaves obrigatórias) que devem ser incluídas em todas as chamadas de criptografia e descriptografia.

nota

O contexto de criptografia necessário (CMM) só é interoperável com a versão 4. x do AWS Encryption SDK para o.NET. Não é interoperável com nenhuma outra implementação de linguagem de programação. Se você criptografar dados usando o contexto de criptografia necessário CMM, só poderá descriptografá-los com a versão 3. x do AWS Encryption SDK for Java ou versão 4. x do AWS Encryption SDK para o.NET.

Ao criptografar, o AWS Encryption SDK verifica se todas as chaves de contexto de criptografia necessárias estão incluídas no contexto de criptografia que você especificou. O AWS Encryption SDK sinaliza os contextos de criptografia que você especificou. Somente os pares de chave/valor que não são chaves obrigatórias são serializados e armazenados em texto simples no cabeçalho da mensagem criptografada retornada pela operação de criptografia.

Ao descriptografar, você deve fornecer um contexto de criptografia que contenha todos os pares de chave/valor que representam as chaves necessárias. O AWS Encryption SDK usa esse contexto de criptografia e os pares de chave/valor armazenados no cabeçalho da mensagem criptografada para reconstruir o contexto de criptografia original que você especificou na operação de criptografia. Se o AWS Encryption SDK não puder reconstruir o contexto de criptografia original, a operação de descriptografia falhará. Se você fornecer um par de chave/valor que contenha a chave necessária com um valor incorreto, a mensagem criptografada não poderá ser descriptografada. Você deve fornecer o mesmo par de chave/valor especificado na criptografia.

Importante

Considere cuidadosamente quais valores você escolhe para as chaves necessárias no contexto de criptografia. Você deverá fornecer as mesmas chaves e os valores correspondentes novamente na descriptografia. Se você não conseguir reproduzir as chaves necessárias, a mensagem criptografada não poderá ser descriptografada.

O exemplo a seguir inicializa um token de autenticação do AWS KMS com o CMM de contexto de criptografia necessário.


// 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()
        );

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Exemplos