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á. # Migração do SDK do AWS CloudHSM cliente 3 para o SDK do cliente 5 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 Client SDK 3 inclui duas ferramentas de linha de comando separadas: o CMU para gerenciar usuários e a KMU para gerenciar chaves e realizar operações com chaves. O Client SDK 5 consolida as funções do CMU e do KMU (ferramentas que foram oferecidas com o Client SDK 3) em uma única ferramenta, a [AWS CloudHSM Interface de linha de comando (CLI)](cloudhsm_cli.md). As operações de gerenciamento de usuários podem ser encontradas nos subcomandos contidos em [A categoria user na CLI do CloudHSM](cloudhsm_cli-user.md) e [A categoria de quórum na CloudHSM CLI](cloudhsm_cli-qm.md). As operações de gerenciamento de chaves podem ser encontradas no [subcomando key](cloudhsm_cli-key.md) e as operações criptográficas podem ser encontradas no [subcomando crypto](cloudhsm_cli-crypto.md). Consulte [Referência para comandos da CLI do CloudHSM](cloudhsm_cli-reference.md) para obter uma lista completa dos comandos. Para conhecer os benefícios da migração, consulte [Benefícios do AWS CloudHSM Client SDK 5](client-sdk-5-benefits.md). Consulte os tópicos a seguir para obter instruções detalhadas sobre a migração do Client SDK 3 para o Client SDK 5. A versão mais recente do SDK AWS CloudHSM do cliente é a 5.16. + [Migre sua biblioteca AWS CloudHSM PKCS \$111 do SDK do cliente 3 para o SDK do cliente 5](pkcs11-migrate-to-sdk-5.md) + [Migre seu OpenSSL Dynamic Engine do AWS CloudHSM Client SDK 3 para o Client SDK 5](openssl-migrate-to-sdk-5.md) + [Migre seu provedor de armazenamento de chaves (KSP) do SDK do AWS CloudHSM cliente 3 para o SDK do cliente 5](ksp-migrate-to-sdk-5.md) + [Migre seu provedor de JCE do AWS CloudHSM Client SDK 3 para o Client SDK 5](java-lib-migrate_to_sdk5.md) Para funcionalidades ou casos de uso que não são compatíveis com a CloudHSM CLI, entre em contato com [AWS Support](https://support.console.aws.amazon.com/support/home#/). # Migre sua biblioteca AWS CloudHSM PKCS \$111 do SDK do cliente 3 para o SDK do cliente 5 Use este tópico para migrar sua [biblioteca AWS CloudHSM PKCS \$111](pkcs11-library.md) do SDK do cliente 3 para o SDK do cliente 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. 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). ## Preparar-se abordando as mudanças mais importantes Revise essas alterações importantes e atualize a aplicação em seu ambiente de desenvolvimento adequadamente. ### Os mecanismos de encapsulamento foram alterados **** | Mecanismo do Client SDK 3 | Mecanismo equivalente do Client SDK 5 | | --- | --- | | `CKM_AES_KEY_WRAP` | `CKM_CLOUDHSM_AES_KEY_WRAP_PKCS5_PAD` | | `CKM_AES_KEY_WRAP_PAD` | `CKM_CLOUDHSM_AES_KEY_WRAP_ZERO_PAD` | | `CKM_CLOUDHSM_AES_KEY_WRAP_PKCS5_PAD` | `CKM_CLOUDHSM_AES_KEY_WRAP_PKCS5_PAD` | | `CKM_CLOUDHSM_AES_KEY_WRAP_NO_PAD` | `CKM_CLOUDHSM_AES_KEY_WRAP_NO_PAD` | | `CKM_CLOUDHSM_AES_KEY_WRAP_ZERO_PAD` | `CKM_CLOUDHSM_AES_KEY_WRAP_ZERO_PAD` | ### ECDH No Client SDK 3, você pode usar o ECDH e especificar um KDF. No momento, essa funcionalidade não está disponível no Client SDK 5. Se sua aplicação precisar dessa funcionalidade, entre em contato com o [suporte](https://support.console.aws.amazon.com/support/home#/). ### Os manipuladores de chaves agora são específicos da sessão Para usar com sucesso os identificadores de chave no Client SDK 5, você deve obter identificadores de chave sempre que executar um aplicativo. Se você tiver aplicações existentes que usarão os mesmos identificadores de chave em diferentes execuções, você deve modificar seu código para obter o identificador de chave sempre que executar a aplicação. Para obter informações sobre como recuperar identificadores de chave, consulte [este exemplo de AWS CloudHSM PKCS \$111](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/find_objects/find_objects.c). Essa alteração está em conformidade com a especificação [PKCS \$111 2.40](http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html#_Toc416959689). ## 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, o 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. Desinstale a biblioteca PKCS \$111 para Client SDK 3. ------ #### [ Amazon Linux 2 ] ``` $ sudo yum remove cloudhsm-client-pkcs11 ``` ------ #### [ CentOS 7 ] ``` $ sudo yum remove cloudhsm-client-pkcs11 ``` ------ #### [ RHEL 7 ] ``` $ sudo yum remove cloudhsm-client-pkcs11 ``` ------ #### [ RHEL 8 ] ``` $ sudo yum remove cloudhsm-client-pkcs11 ``` ------ #### [ Ubuntu 16.04 LTS ] ``` $ sudo apt remove cloudhsm-client-pkcs11 ``` ------ #### [ Ubuntu 18.04 LTS ] ``` $ sudo apt remove cloudhsm-client-pkcs11 ``` ------ 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 a biblioteca PKCS \$111 do Client SDK seguindo as etapas em [Instale a biblioteca PKCS \$111 para o AWS CloudHSM Client SDK 5](pkcs11-library-install.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 sua biblioteca PKCS \$111 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) # Migre seu OpenSSL Dynamic Engine do AWS CloudHSM Client SDK 3 para o Client SDK 5 Use este tópico para migrar seu [OpenSSL Dynamic Engine](openssl-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. **nota** Atualmente, não há suporte para a geração de números aleatórios no Client SDK 5 com OpenSSL Dynamic Engine. 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). ## 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, o 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. Desinstale o OpenSSL Dynamic Engine para Client SDK 3. ------ #### [ Amazon Linux 2 ] ``` $ sudo yum remove cloudhsm-client-dyn ``` ------ #### [ CentOS 7 ] ``` $ sudo yum remove cloudhsm-client-dyn ``` ------ #### [ RHEL 7 ] ``` $ sudo yum remove cloudhsm-client-dyn ``` ------ #### [ RHEL 8 ] ``` $ sudo yum remove cloudhsm-client-dyn ``` ------ #### [ Ubuntu 16.04 LTS ] ``` $ sudo apt remove cloudhsm-client-dyn ``` ------ #### [ Ubuntu 18.04 LTS ] ``` $ sudo apt remove cloudhsm-client-dyn ``` ------ 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 OpenSSL Dynamic Engine do Client SDK seguindo as etapas em [Instale o OpenSSL Dynamic Engine AWS CloudHSM for Client SDK 5](openssl5-install.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 OpenSSL Dynamic Engine 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) # Migre seu provedor de armazenamento de chaves (KSP) do SDK do AWS CloudHSM cliente 3 para o SDK do cliente 5 Este tópico explica como migrar seu [Provedor de armazenamento de chaves (KSP)](ksp-library.md) do Client SDK 3 do AWS CloudHSM para o Client SDK 5 A versão mais recente do SDK AWS CloudHSM do cliente é a 5.16. Para obter informações sobre os benefícios da migração, consulte [Benefícios do AWS CloudHSM Client SDK 5](client-sdk-5-benefits.md). Em AWS CloudHSM, você usa o AWS CloudHSM Client Software Development Kit (SDK) para realizar operações criptográficas. O Client SDK 5 é o SDK principal que recebe novos atributos e atualizações de suporte de plataforma. Para obter 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). ## Migrar para o Client SDK 5 1. Pare o Client Daemon para o Client SDK 3. ``` PS C:\> Stop-Service "AWS CloudHSM Client" ``` 1. Instale o Provedor de armazenamento de chaves (KSP) do Client SDK 5 na sua instância do Windows Server. Para instruções, consulte [Instale o provedor de armazenamento de chaves (KSP) para o AWS CloudHSM Client SDK 5](ksp-library-install.md). 1. Configure o Provedor de armazenamento de chaves (KSP) do Client SDK 5 usando o novo formato de arquivo de configuração e a ferramenta de inicialização de linha de comando. Para instruções, consulte [Bootstrap o Client SDK](cluster-connect.md#connect-how-to). 1. O Key Storage Provider (KSP) para o AWS CloudHSM Client SDK 5 inclui o modo de SDK3 compatibilidade para oferecer suporte aos principais arquivos de referência gerados em. SDK3 Para obter mais informações, consulte [SDK3 modo de compatibilidade do Key Storage Provider (KSP) para AWS CloudHSM](ksp-library-configs-sdk3-compatibility-mode.md). **nota** Você deve ativar o modo de SDK3 compatibilidade ao usar os arquivos de referência de chave gerados pelo Client SDK 3 com o Client SDK 5. ## Migrar para novas instâncias do Windows Server 1. Conclua todas as etapas em [Migrar para o Client SDK 5](#ksp-migrate-steps) em suas novas instâncias do Windows Server. 1. **Verificar arquivos de referência de chaves existentes** Em sua instância original do Windows Server, verifique os arquivos de referência chave em `C:\Users\Default\AppData\Roaming\Microsoft\Crypto\CaviumKSP\GlobalPartition`. + Se existirem arquivos de referência chave, copie todo o conteúdo em `C:\Users\Default\AppData\Roaming\Microsoft\Crypto\CaviumKSP` incluindo `GlobalPartition`, para o mesmo caminho de diretório na sua nova instância do Windows Server. Crie o diretório, caso ele ainda não exista. + Se os arquivos de referência chave não existirem, use `cloudhsm-cli key generate-file --encoding ksp-key-reference` em sua nova instância do Windows Server para criá-los. Para instruções, consulte [Gerar referências de chave KSP (Windows)](cloudhsm_cli-key-generate-file.md#key-generate-ksp-key-reference). 1. **Verificar um certificado raiz** Verifique seu certificado raiz nas autoridades de certificação raiz confiáveis: ``` PS C:\Users\Administrator\Desktop> certutil -store Root Root "Trusted Root Certification Authorities" ================ Certificate 0 ================ Serial Number: certificate-serial-number Issuer: CN=MYRootCA NotBefore: 2/5/2020 1:38 PM NotAfter: 2/5/2021 1:48 PM Issuer: CN=MYRootCA Signature matches Public Key Root Certificate: Subject matches Issuer Cert Hash(sha1): cert-hash No key provider information Cannot find the certificate and private key for decryption. CertUtil: -store command completed successfully. ``` **nota** Anote o número de série do certificado para uso na próxima etapa. 1. **Exportar um certificado raiz** Exporte o certificado raiz para um arquivo: ``` certutil -store Root certificate-serial-number root-certificate-name.cer ``` 1. **Verificar o certificado de backend do HSM** Verifique seu certificado de backend do HSM no repositório de certificados pessoais: ``` PS C:\Users\Administrator\Desktop> certutil -store My my "Personal" ================ Certificate 0 ================ Serial Number: certificate-serial-number Issuer: CN=MYRootCA NotBefore: 2/5/2020 1:38 PM NotAfter: 2/5/2021 1:48 PM Subject: CN=www.mydomain.com, OU=Certificate Management, O=Information Technology, L=Houston, S=Texas, C=US Non-root Certificate Cert Hash(sha1): cert-hash Key Container = key-container-name Provider = Cavium Key Storage Provider Private key is NOT exportable Encryption test passed CertUtil: -store command completed successfully. ``` **nota** Anote o número de série do certificado para uso na próxima etapa. 1. **Exportar certificado de backend do HSM** Exporte o certificado de backend do HSM para um arquivo: ``` certutil -store My certificate-serial-number signed-certificate-name.cer ``` 1. **Importar um certificado raiz** Na sua nova instância do Windows: 1. Copie o arquivo CA raiz para sua nova instância do Windows 1. Importe o certificado: ``` certutil -addstore Root root-certificate-name.cer ``` 1. **Verificar a instalação do certificado raiz** Confirme se o certificado raiz foi instalado corretamente: ``` PS C:\Users\Administrator\Desktop> certutil -store Root Root "Trusted Root Certification Authorities" ================ Certificate 0 ================ Serial Number: certificate-serial-number Issuer: CN=MYRootCA NotBefore: 2/5/2020 1:38 PM NotAfter: 2/5/2021 1:48 PM Issuer: CN=MYRootCA Signature matches Public Key Root Certificate: Subject matches Issuer Cert Hash(sha1): cert-hash No key provider information Cannot find the certificate and private key for decryption. CertUtil: -store command completed successfully. ``` 1. **Importar um certificado de backend do HSM** Na sua nova instância do Windows: 1. Copie o certificado de backend do HSM para sua nova instância do Windows 1. Importe o certificado: ``` certutil -addstore My signed-certificate-name.cer ``` 1. **Verificar a instalação do certificado de backend do HSM** Confirme se o certificado de backend do HSM foi instalado corretamente: ``` PS C:\Users\Administrator\Desktop> certutil -store My my "Personal" ================ Certificate 0 ================ Serial Number: certificate-serial-number Issuer: CN=MYRootCA NotBefore: 2/5/2020 1:38 PM NotAfter: 2/5/2021 1:48 PM Subject: CN=www.mydomain.com, OU=Certificate Management, O=Information Technology, L=Houston, S=Texas, C=US Non-root Certificate Cert Hash(sha1): cert-hash No key provider information Cannot find the certificate and private key for decryption. CertUtil: -store command completed successfully. ``` **nota** Anote o número de série do certificado para uso nas próximas etapas. 1. **Criar um arquivo de referência de chaves (opcional)** Conclua esta etapa somente se precisar criar um novo arquivo de referência de chave. Caso contrário, siga para a próxima etapa. **nota** Esse atributo só está disponível no SDK versão 5.16.0 e posterior. 1. Instale o [OpenSSL](https://slproweb.com/products/Win32OpenSSL.html) e extraia o módulo: ``` openssl x509 -in signed-certificate-name.cer -modulus -noout ``` **nota** O comando OpenSSL gera o módulo no formato: `Modulus=modulus-value`. Observe o *modulus-value* para uso no próximo comando. 1. Crie um arquivo de referência chave com a CloudHSM CLI, consulte: [Gerar referências de chave KSP (Windows)](cloudhsm_cli-key-generate-file.md#key-generate-ksp-key-reference) ``` & "C:\Program Files\Amazon\CloudHSM\bin\cloudhsm-cli.exe" key generate-file --encoding ksp-key-reference --filter attr.class=private-key attr.modulus=0xmodulus-value ``` **nota** Os argumentos do comando *modulus-value* na CLI do CloudHSM devem ser `0x` prefixados com para indicar o formato hexadecimal. Os principais arquivos de referência são criados em `C:\Users\Default\AppData\Roaming\Microsoft\Crypto\CaviumKSP\GlobalPartition`. 1. **Criar configuração de restauração** Crie um arquivo chamado `repair.txt` com o seguinte conteúdo: ``` [Properties] 11 = "" ; Add friendly name property 2 = "{text}" ; Add Key Provider Information property _continue_="Container=key-container-name&" _continue_="Provider=Cavium Key Storage Provider&" _continue_="Flags=0&" _continue_="KeySpec=2" ``` **nota** *key-container-name*Substitua pelo nome do arquivo de referência chave de. `C:\Users\Default\AppData\Roaming\Microsoft\Crypto\CaviumKSP\GlobalPartition` 1. **Reparar o armazenamento de certificados** Execute o comando repair: ``` certutil -repairstore My certificate-serial-number repair.txt ``` **nota** O número de série do certificado é obtido nas etapas anteriores ao verificar a instalação do certificado de backend do HSM. 1. **Verificar uma associação de certificados** Confirme se o certificado foi associado corretamente: ``` PS C:\Users\Administrator\Desktop> certutil -store My my "Personal" ================ Certificate 0 ================ Serial Number: certificate-serial-number Issuer: CN=MYRootCA NotBefore: 2/5/2020 1:38 PM NotAfter: 2/5/2021 1:48 PM Subject: CN=www.mydomain.com, OU=Certificate Management, O=Information Technology, L=Houston, S=Texas, C=US Non-root Certificate Cert Hash(sha1): cert-hash Key Container = key-container-name Provider = Cavium Key Storage Provider Private key is NOT exportable ERROR: Could not verify certificate public key against private key CertUtil: -store command completed successfully. ``` Verifique se a saída mostra: + O nome correto do contêiner de chaves + O Cavium Key Storage Provider + Esse `ERROR: Could not verify certificate public key against private key` é um problema conhecido, consulte [Problema: falha na verificação de um armazenamento de certificados](ki-ksp-sdk.md#ki-ksp-1) 1. **Testar a aplicação** Antes de concluir a migração: 1. Teste sua aplicação em seu ambiente de desenvolvimento. 1. Atualize seu código para resolver quaisquer alterações importantes 1. Para obter orientação específica da aplicação, consulte [Integrando aplicativos de terceiros com AWS CloudHSM](third-party-applications.md) ## Verificar a migração Depois de concluir as etapas de migração, verifique se: + Seus certificados estão instalados corretamente nos repositórios de certificados corretos + Os principais arquivos de referência estão presentes no local correto + Sua aplicação pode realizar operações criptográficas usando os certificados migrados ## Solução de problemas Se você encontrar problemas durante a migração, verifique: + Todos os certificados são exportados corretamente do sistema de origem + Os números de série do certificado coincidem entre os sistemas + Os nomes dos contêineres principais no arquivo repair.txt correspondem aos seus arquivos de referência de chave + SDK3 o modo de compatibilidade é ativado se estiver usando arquivos SDK3 de referência de chave gerados ## Tópicos relacionados + [Melhores práticas para AWS CloudHSM](best-practices.md) # 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)