Pré-requisitos Instalação AWS KMS chaveiros Contexto de criptografia necessário CMM

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 o AWS Encryption SDK for Java, consulte o aws-encryption-sdk-javarepositório em GitHub. Para obter a API documentação, consulte o Javadoc para o. AWS Encryption SDK for Java

Pré-requisitos

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

Um ambiente de desenvolvimento Java

Você precisará do Java 8 ou posterior. No site da Oracle, acesse Downloads do Java SE e, em seguida, baixe e instale o Java SE Development Kit (JDK).

Se você usa o OracleJDK, também deve baixar e instalar os Arquivos de Política de Jurisdição de Força Ilimitada da Extensão de Criptografia Java (JCE).

Bouncy Castle

AWS Encryption SDK for Java Isso requer o Bouncy Castle.

AWS Encryption SDK for Java as versões 1.6.1 e posteriores usam o Bouncy Castle para serializar e desserializar objetos criptográficos. Você pode usar o Bouncy Castle ou o Bouncy Castle FIPS para satisfazer esse requisito. Para obter ajuda na instalação e configuração do Bouncy CastleFIPS, consulte a FIPSdocumentação do BC, especialmente os guias do usuário e a política de segurança. PDFs
As versões anteriores do AWS Encryption SDK for Java usam a criptografia API do Bouncy Castle para Java. Este requisito é satisfeito apenas por pessoas que não são do FIPS Bouncy Castle.

Se você não tem o Bouncy Castle, acesse as últimas versões do Bouncy Castle para baixar o arquivo do provedor que corresponde ao 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 (bc-fips). FIPS

AWS SDK for Java

Versão 3. x of the AWS Encryption SDK for Java requer o AWS 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, AWS SDK for Java é necessário usar AWS Key Management Service(AWS KMS) como provedor de chave mestra. A partir da AWS Encryption SDK for Java versão 2.4.0, o AWS Encryption SDK for Java suporta as versões 1.x e 2.x do. AWS SDK for Java AWS Encryption SDK os códigos para AWS SDK for Java 1.x e 2.x são interoperáveis. Por exemplo, você pode criptografar dados com AWS Encryption SDK código compatível com AWS SDK for Java 1.x e descriptografá-los usando código compatível AWS SDK for Java 2.x (ou vice-versa). As versões AWS Encryption SDK for Java anteriores à 2.4.0 suportam apenas AWS SDK for Java 1.x. Para obter informações sobre como atualizar sua versão do AWS Encryption SDK, consulteComo migrar seu AWS Encryption SDK.

Ao atualizar seu AWS Encryption SDK for Java código de AWS SDK for Java 1.x para AWS SDK for Java 2.x, substitua as referências à AWSKMSinterface em AWS SDK for Java 1.x por referências à KmsClientinterface em. AWS SDK for Java 2.x O AWS Encryption SDK for Java não suporta a KmsAsyncClientinterface. Além disso, atualize seu código para usar os objetos AWS KMS relacionados no kmssdkv2 namespace, em vez do kms namespace.

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 AWS KMS módulo na AWS SDK for Java versão 1.x, siga as instruções para especificar módulos específicos e defina o. artifactId aws-java-sdk-kms
Para criar uma dependência somente para o AWS KMS módulo na AWS SDK for Java versão 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 O que há de diferente entre a AWS SDK for Java versão 1.x e a 2.x no Guia do AWS SDK for Java 2.x desenvolvedor.

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

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 do AWS Encryption SDK. Para obter detalhes, consulte Como migrar seu AWS Encryption SDK.

Você pode instalar o AWS Encryption SDK for Java das seguintes maneiras.

Manualmente

Para instalar o AWS 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 seguinte definição de dependência.


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

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

AWS KMS chaveiros 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 AWS Encryption SDK for Java levam apenas uma KMS chave. Eles também exigem um AWS KMS cliente, o que lhe dá a oportunidade Região da AWS de configurar o cliente para a KMS chave.

Para criar um AWS KMS chaveiro com uma ou mais teclas de embrulho, use um chaveiro múltiplo. AWS Encryption SDK for Java Tem 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 Java Ele 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 chaveiro com uma ou mais AWS KMS chaves, use o CreateAwsKmsMultiKeyring() método. Este exemplo usa duas chaves do KMS. Para especificar uma KMS chave, use somente o generator parâmetro. O msKeyIds parâmetro que especifica KMS chaves adicionais é opcional.

A entrada para este chaveiro não requer um AWS KMS cliente. Em vez disso, AWS Encryption SDK ele usa o AWS KMS cliente padrão para cada região representado por uma KMS chave no chaveiro. Por exemplo, se a KMS chave identificada pelo valor do Generator parâmetro estiver na região Oeste dos EUA (Oregon) (us-west-2), ela AWS Encryption SDK criará um AWS KMS cliente padrão para a us-west-2 região. 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 = materialProviders.CreateAwsKmsMultiKeyring(keyringInput);

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

Para criptografar com um RSA AWS KMS chaveiro 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 AWS KMS chamada é feita ao criptografar com este chaveiro. Para descriptografar com um RSA AWS KMS chaveiro assimétrico, você precisa da permissão kms:Decrypt.

Para criar um RSA AWS KMS chaveiro assimétrico, você deve fornecer a chave pública e a chave privada ARN da sua chave assimétrica. RSA KMS A chave pública deve ser PEM codificada. O exemplo a seguir cria um AWS KMS chaveiro com um par de chaves assimétricoRSA.


// 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 do AWS 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 contexto de criptografia necessárioCMM, você pode 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 só CMM é interoperável com a versão 4. x do AWS Encryption SDK formulário. 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árioCMM, 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 formulário. NET.

Ao criptografar, 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. Os AWS Encryption SDK sinais dos 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 valores-chave armazenados no cabeçalho da mensagem criptografada para reconstruir o contexto de criptografia original que você especificou na operação de criptografia. Se não for AWS Encryption SDK possível 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 AWS KMS chaveiro com o contexto de criptografia necessário. CMM


// 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