As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Migre seu provedor de JCE do AWS CloudHSM Client SDK 3 para o Client SDK 5 Use este tópico para migrar seu [provedor JCE](java-library.md) do Client SDK 3 do AWS CloudHSM para o Client SDK 5. Para conhecer os benefícios da migração, consulte [Benefícios do AWS CloudHSM Client SDK 5](client-sdk-5-benefits.md). Em AWS CloudHSM, os aplicativos do cliente realizam operações criptográficas usando o Kit de Desenvolvimento de Software AWS CloudHSM do Cliente (SDK). O Client SDK 5 é o SDK principal que sempre recebe novos atributos e suporte de plataforma. O provedor Client SDK 3 JCE usa classes personalizadas e APIs que não fazem parte da especificação JCE padrão. O Client SDK 5 para o provedor JCE está em conformidade com a especificação JCE e é incompatível com versões anteriores do Client SDK 3 em determinadas áreas. As aplicações do cliente podem exigir alterações como parte da migração para o Client SDK 5. Esta seção descreve as alterações necessárias para uma migração bem-sucedida. Para revisar as instruções de migração para todos os provedores, consulte [Migração do SDK do AWS CloudHSM cliente 3 para o SDK do cliente 5](client-sdk-migration.md). **Topics** + [Preparar-se abordando as mudanças mais importantes](#jce-migration-preparation-sdk5) + [Migrar para o Client SDK 5](#w2aac25c19c21c15) + [Tópicos relacionados](#java-lib-migrate_to_sdk5-seealso) ## Preparar-se abordando as mudanças mais importantes Revise essas alterações importantes e atualize a aplicação em seu ambiente de desenvolvimento adequadamente. ### A classe e o nome do provedor foram alterados **** | O que mudou | O que estava no Client SDK 3 | O que está no Client SDK 5 | Exemplo | | --- | --- | --- | --- | | Classe e nome do provedor | A classe de provedor JCE no Client SDK 3 é chamada de `CaviumProvider` e tem o nome de provedor `Cavium`. | No Client SDK 5, a classe Provider é chamada de `CloudHsmProvider` e tem o nome de provedor `CloudHSM`. | Um exemplo de como inicializar o `CloudHsmProvider` objeto está disponível no [repositório de AWS CloudHSM GitHub amostra](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/AESGCMEncryptDecryptRunner.java#L43-L50). | ### O login explícito foi alterado, o implícito não **** | O que mudou | O que estava no Client SDK 3 | O que está no Client SDK 5 | Exemplo | | --- | --- | --- | --- | | Login explícito | O Client SDK 3 usa a classe `LoginManager` para o login explícito [1](#explicit_login_sdk3_note). | No Client SDK 5, o provedor `CloudHSM` implementa `AuthProvider` para o login explícito. `AuthProvider` é uma classe Java padrão e segue a forma idiomática do Java de fazer login em um provedor. Com o gerenciamento aprimorado do estado de login no Client SDK 5, as aplicações não precisam mais monitorar e realizar o login durante as reconexões[2](#explicit_login_sdk5_note). | Para ver um exemplo de como usar o login explícito com o SDK 5 do cliente, consulte o LoginRunner exemplo no repositório de amostras do [AWS GitHub CloudHSM](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java#L109C5-L141). | | Login implícito | Nenhuma alteração é necessária para o login implícito. O mesmo arquivo de propriedades e todas as variáveis de ambiente continuarão funcionando para o login implícito ao migrar do Client SDK 3 para o Client SDK 5. | Para ver um exemplo de como usar o login implícito com o Client SDK 5, consulte a [LoginRunner AWS CloudHSM GitHub amostra no repositório](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java#L143-L202) de amostras. | + [1] Trecho de código do Client SDK 3: ``` LoginManager lm = LoginManager.getInstance(); lm.login(partition, user, pass); ``` + [2] Trecho de código do Client SDK 5: ``` // Construct or get the existing provider object AuthProvider provider = new CloudHsmProvider(); // Call login method on the CloudHsmProvider object // Here loginHandler is a CallbackHandler provider.login(null, loginHandler); ``` Para ver um exemplo de como usar o login explícito com o Client SDK 5, consulte a [LoginRunner AWS CloudHSM GitHub amostra no repositório](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java#L109C5-L141) de amostras. ### A geração de chaves mudou **** | O que mudou | O que estava no Client SDK 3 | O que está no Client SDK 5 | Exemplo | | --- | --- | --- | --- | | Geração de chaves | No Client SDK 3, `Cavium[Key-type]AlgorithmParameterSpec` é usado para especificar parâmetros de geração de chaves. Para obter um trecho de código, consulte a nota de rodapé [1](#key_generation_sdk3_note). | No Client SDK 5, `KeyAttributesMap` é usado para especificar atributos de geração de chaves. Para obter um trecho de código, consulte a nota de rodapé [2](#key_generation_sdk5_note). | Para ver um exemplo de como usar `KeyAttributesMap` para gerar uma chave simétrica, consulte a [SymmetricKeys amostra no repositório de amostras](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/SymmetricKeys.java) do GitHub AWS CloudHSM. | | Geração de pares de chaves | No Client SDK 3, `Cavium[Key-type]AlgorithmparameterSpec` é usado para especificar parâmetros de geração de pares de chaves. Para obter um trecho de código, consulte a nota de rodapé [3](#key_pair_generation_sdk3_note). | No Client SDK 5, `KeyPairAttributesMap` é usado para especificar esses parâmetros. Para obter um trecho de código, consulte a nota de rodapé [4](#key_pair_generation_sdk5_note). | Para ver um exemplo de como usar `KeyAttributesMap` para gerar uma chave assimétrica, consulte a [AsymmetricKeys amostra no repositório](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/AsymmetricKeys.java) de AWS CloudHSM GitHub amostras. | + [1] Trecho de código de geração de chaves do Client SDK 3: ``` KeyGenerator keyGen = KeyGenerator.getInstance("AES", "Cavium"); CaviumAESKeyGenParameterSpec aesSpec = new CaviumAESKeyGenParameterSpec( keySizeInBits, keyLabel, isExtractable, isPersistent); keyGen.init(aesSpec); SecretKey aesKey = keyGen.generateKey(); ``` + [2] Trecho de código de geração de chaves do Client SDK 5: ``` KeyGenerator keyGen = KeyGenerator.getInstance("AES", CloudHsmProvider.PROVIDER_NAME); final KeyAttributesMap aesSpec = new KeyAttributesMap(); aesSpec.put(KeyAttribute.LABEL, keyLabel); aesSpec.put(KeyAttribute.SIZE, keySizeInBits); aesSpec.put(KeyAttribute.EXTRACTABLE, isExtractable); aesSpec.put(KeyAttribute.TOKEN, isPersistent); keyGen.init(aesSpec); SecretKey aesKey = keyGen.generateKey(); ``` + [3] Trecho de código de geração de pares de chaves do Client SDK 3: ``` KeyPairGenerator keyPairGen = KeyPairGenerator.getInstance("rsa", "Cavium"); CaviumRSAKeyGenParameterSpec spec = new CaviumRSAKeyGenParameterSpec( keySizeInBits, new BigInteger("65537"), label + ":public", label + ":private", isExtractable, isPersistent); keyPairGen.initialize(spec); keyPairGen.generateKeyPair(); ``` + [4] Trecho do código de geração de pares de chaves do Client SDK 5: ``` KeyPairGenerator keyPairGen = KeyPairGenerator.getInstance("RSA", providerName); // Set attributes for RSA public key final KeyAttributesMap publicKeyAttrsMap = new KeyAttributesMap(); publicKeyAttrsMap.putAll(additionalPublicKeyAttributes); publicKeyAttrsMap.put(KeyAttribute.LABEL, label + ":Public"); publicKeyAttrsMap.put(KeyAttribute.MODULUS_BITS, keySizeInBits); publicKeyAttrsMap.put(KeyAttribute.PUBLIC_EXPONENT, new BigInteger("65537").toByteArray()); // Set attributes for RSA private key final KeyAttributesMap privateKeyAttrsMap = new KeyAttributesMap(); privateKeyAttrsMap.putAll(additionalPrivateKeyAttributes); privateKeyAttrsMap.put(KeyAttribute.LABEL, label + ":Private"); // Create KeyPairAttributesMap and use that to initialize the // keyPair generator KeyPairAttributesMap keyPairSpec = new KeyPairAttributesMapBuilder() .withPublic(publicKeyAttrsMap) .withPrivate(privateKeyAttrsMap) .build(); keyPairGen.initialize(keyPairSpec); keyPairGen.generateKeyPair(); ``` ### As chaves de localização, exclusão e referência foram alteradas Encontrar uma chave já gerada AWS CloudHSM envolve o uso do KeyStore. O SDK 3 do cliente tem dois KeyStore tipos: `Cavium` e. `CloudHSM` O SDK 5 do cliente tem apenas um KeyStore tipo:`CloudHSM`. `Cavium` KeyStore Mudar do para `CloudHSM` KeyStore requer uma mudança de KeyStore tipo. Além disso, o Client SDK 3 usa identificadores de chave para fazer referência a chaves, enquanto o Client SDK 5 usa rótulos de chave. As mudanças de comportamento resultantes são as mencionadas a seguir. | O que mudou | O que estava no Client SDK 3 | O que está no Client SDK 5 | Exemplo | | --- | --- | --- | --- | | Referências de chave | Com o Client SDK 3, as aplicações usam rótulos ou identificadores de chaves para fazer referência a chaves no HSM. Eles usam rótulos com KeyStore para encontrar uma chave ou usam alças para criar `CaviumKey` objetos. | No Client SDK 5, as aplicações podem usar o [AWS CloudHSM KeyStore Classe Java para Client SDK 5](alternative-keystore_5.md) para encontrar chaves por rótulo. Para encontrar as chaves pela alça, use o AWS CloudHSM `KeyStoreWithAttributes` com AWS CloudHSM `KeyReferenceSpec`. | | | Descobrir várias entradas | Ao pesquisar uma chave usando`getEntry`,`getKey`, ou `getCertificate` em cenários em que existem vários itens com os mesmos critérios no `Cavium` KeyStore, somente a primeira entrada encontrada será retornada. | Com o AWS CloudHSM `KeyStore` e`KeyStoreWithAttributes`, esse mesmo cenário resultará no lançamento de uma exceção. Para corrigir esse problema, é recomendável definir rótulos exclusivos para chaves usando o comando [Definir os atributos das chaves com a CloudHSM CLI](cloudhsm_cli-key-set-attribute.md) na CLI do CloudHSM. Ou use `KeyStoreWithAttributes#getKeys` para retornar todas as chaves correspondentes aos critérios. | | | Encontrar todas as chaves | No Client SDK 3, é possível encontrar todas as chaves no HSM usando `Util.findAllKeys()`. | O Client SDK 5 torna a descoberta de chaves mais simples e eficiente usando a classe `KeyStoreWithAttributes`. Quando possível, armazene suas chaves em cache para minimizar a latência. Para obter mais informações, consulte [Gerencie com eficácia as chaves em seu aplicativo](bp-application-integration.md#bp-manage-application). Quando precisar recuperar todas as chaves do HSM, use `KeyStoreWithAttributes#getKeys` com um `KeyAttributesMap` vazio. | Um exemplo que usa a `KeyStoreWithAttributes` classe para encontrar uma chave está disponível no [repositório de AWS CloudHSM GitHub amostra](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java#L205-L223) e um trecho de código é exibido em. [1](#using_keystore_att_note) | | Exclusão de chaves | O Client SDK 3 usa `Util.deleteKey()` para excluir uma chave. | O objeto `Key` no Client SDK 5 implementa a interface `Destroyable`, que permite excluir as chaves usando o método `destroy()` dessa interface. | Um exemplo de código mostrando a funcionalidade de exclusão da chave pode ser encontrado no repositório de amostra do [ GitHub CloudHSM](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java#L229-L234). Um trecho de amostra para cada SDK é mostrado em [2](#delete_key_note). | + [1] Um trecho é mostrado abaixo: ``` KeyAttributesMap findSpec = new KeyAttributesMap(); findSpec.put(KeyAttribute.LABEL, label); findSpec.put(KeyAttribute.KEY_TYPE, keyType); KeyStoreWithAttributes keyStore = KeyStoreWithAttributes.getInstance("CloudHSM"); keyStore.load(null, null); keyStore.getKey(findSpec); ``` + [2] Exclusão de uma chave no Client SDK 3: ``` Util.deleteKey(key); ``` Exclusão de uma chave no Client SDK 5: ``` ((Destroyable) key).destroy(); ``` ### As operações de desencapsulamento de cifras foram alteradas, outras operações de cifragem não **nota** Nenhuma alteração é necessária para as operações de criptografia. encrypt/decrypt/wrap As operações de desencapsulamento exigem que a classe `CaviumUnwrapParameterSpec` do Client SDK 3 seja substituída por uma das seguintes classes específicas das operações criptográficas listadas. + `GCMUnwrapKeySpec` para desencapsulamento `AES/GCM/NoPadding` + `IvUnwrapKeySpec` para `AESWrap unwrap` e `AES/CBC/NoPadding unwrap` + `OAEPUnwrapKeySpec` para `RSA OAEP unwrap` Trecho de exemplo para `OAEPUnwrapkeySpec`: ``` OAEPParameterSpec oaepParameterSpec = new OAEPParameterSpec( "SHA-256", "MGF1", MGF1ParameterSpec.SHA256, PSpecified.DEFAULT); KeyAttributesMap keyAttributesMap = new KeyAttributesMap(KeyAttributePermissiveProfile.KEY_CREATION); keyAttributesMap.put(KeyAttribute.TOKEN, true); keyAttributesMap.put(KeyAttribute.EXTRACTABLE, false); OAEPUnwrapKeySpec spec = new OAEPUnwrapKeySpec(oaepParameterSpec, keyAttributesMap); Cipher hsmCipher = Cipher.getInstance( "RSA/ECB/OAEPPadding", CloudHsmProvider.PROVIDER_NAME); hsmCipher.init(Cipher.UNWRAP_MODE, key, spec); ``` ### As operações de assinatura não foram alteradas Nenhuma alteração é necessária para as operações de assinatura. ## Migrar para o Client SDK 5 Siga as instruções nesta seção para migrar do Client SDK 3 para o Client SDK 5. **nota** No momento, o Amazon Linux, o Ubuntu 16.04, o Ubuntu 18.04 CentOS 6, o CentOS 8 e o RHEL 6 não são compatíveis com o Client SDK 5. Se você estiver usando uma dessas plataformas com o Client SDK 3, precisará escolher uma plataforma diferente ao migrar para o Client SDK 5. 1. Desinstalar o provedor JCE para o Client SDK 3. ------ #### [ Amazon Linux 2 ] ``` $ sudo yum remove cloudhsm-client-jce ``` ------ #### [ CentOS 7 ] ``` $ sudo yum remove cloudhsm-client-jce ``` ------ #### [ RHEL 7 ] ``` $ sudo yum remove cloudhsm-client-jce ``` ------ #### [ RHEL 8 ] ``` $ sudo yum remove cloudhsm-client-jce ``` ------ #### [ Ubuntu 16.04 LTS ] ``` $ sudo apt remove cloudhsm-client-jce ``` ------ #### [ Ubuntu 18.04 LTS ] ``` $ sudo apt remove cloudhsm-client-jce ``` ------ 1. Pare o Client Daemon para o Client SDK 3. ------ #### [ Amazon Linux 2 ] ``` $ sudo service cloudhsm-client stop ``` ------ #### [ CentOS 7 ] ``` $ sudo service cloudhsm-client stop ``` ------ #### [ RHEL 7 ] ``` $ sudo service cloudhsm-client stop ``` ------ #### [ RHEL 8 ] ``` $ sudo service cloudhsm-client stop ``` ------ #### [ Ubuntu 16.04 LTS ] ``` $ sudo systemctl stop cloudhsm-client ``` ------ #### [ Ubuntu 18.04 LTS ] ``` $ sudo systemctl stop cloudhsm-client ``` ------ 1. Desinstale o Client Daemon do Client SDK 3. ------ #### [ Amazon Linux 2 ] ``` $ sudo yum remove cloudhsm-client ``` ------ #### [ CentOS 7 ] ``` $ sudo yum remove cloudhsm-client ``` ------ #### [ RHEL 7 ] ``` $ sudo yum remove cloudhsm-client ``` ------ #### [ RHEL 8 ] ``` $ sudo yum remove cloudhsm-client ``` ------ #### [ Ubuntu 16.04 LTS ] ``` $ sudo apt remove cloudhsm-client ``` ------ #### [ Ubuntu 18.04 LTS ] ``` $ sudo apt remove cloudhsm-client ``` ------ **nota** As configurações personalizadas precisam ser habilitadas novamente. 1. Instale o provedor JCE do Client SDK seguindo as etapas em [Instale o provedor JCE para o AWS CloudHSM Client SDK 5](java-library-install_5.md). 1. O Client SDK 5 apresenta um novo formato de arquivo de configuração e uma ferramenta de inicialização de linha de comando. Para inicializar seu provedor JCE do Client SDK 5, siga as instruções listadas no guia do usuário em [Bootstrap o Client SDK](cluster-connect.md#connect-how-to). 1. Teste sua aplicação em seu ambiente de desenvolvimento. Faça atualizações no código existente para resolver as alterações importantes antes da migração final. ## Tópicos relacionados + [Melhores práticas para AWS CloudHSM](best-practices.md)