Preparar-se abordando as mudanças mais importantes Migrar para o Client SDK 5 Tópicos relacionados

Migrar seu provedor JCE do Client SDK 3 do AWS CloudHSM para o Client SDK 5

Use este tópico para migrar seu provedor JCE do Client SDK 3 do AWS CloudHSM para o Client SDK 5. Para conhecer os benefícios da migração, consulte Benefícios do Client SDK 5 do AWS CloudHSM.

No AWS CloudHSM, as aplicações do cliente realizam operações criptográficas usando o Kit de Desenvolvimento de Software (SDK) do cliente AWS CloudHSM. O Client SDK 5 é o SDK principal que sempre recebe novos recursos e suporte de plataforma.

O provedor JCE do Client SDK 3 usa classes e APIs personalizadas 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 Migrar do Client SDK 3 do AWS CloudHSM para o Client SDK 5.

Tópicos

Preparar-se abordando as mudanças mais importantes
Migrar para o Client SDK 5
Tópicos relacionados

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 objeto `CloudHsmProvider` está disponível no repositório de amostras do AWS CloudHSM GitHub.

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 ¹.	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².	Para ver um exemplo de como usar o login explícito com o SDK 5 do cliente, consulte a amostra do LoginRunner no repositório de amostras do AWS CloudHSM GitHub.
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 SDK 5 do cliente, consulte a amostra do LoginRunner no repositório de amostras do AWS CloudHSM GitHub.

[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 amostra do LoginRunner no repositório de amostras do AWS CloudHSM GitHub.

Mostrar mais

Mostrar menos

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.	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.	Para ver um exemplo de como usar `KeyAttributesMap` para gerar uma chave simétrica, consulte a amostra SymmetricKeys no repositório de amostras do AWS CloudHSM Github.
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.	No Client SDK 5, `KeyPairAttributesMap` é usado para especificar esses parâmetros. Para obter um trecho de código, consulte a nota de rodapé 4.	Para ver um exemplo de como usar `KeyAttributesMap` para gerar uma chave assimétrica, consulte a amostra de AsymmetricKeys no repositório de amostras do AWS CloudHSM GitHub.

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

Mostrar mais

Mostrar menos

As chaves de localização, exclusão e referência foram alteradas

Encontrar uma chave já gerada com AWS CloudHSM envolve o uso do KeyStore. O Client SDK 3 tem dois tipos de KeyStore: Cavium e CloudHSM. O Client SDK 5 tem apenas um tipo de KeyStore: CloudHSM.

A mudança do Cavium KeyStore para o CloudHSM KeyStore requer uma mudança no tipo de KeyStore. 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. Elas usam rótulos com KeyStore para encontrar uma chave ou usam manipuladores para criar objetos `CaviumKey`.	No Client SDK 5, as aplicações podem usar o Classe Java KeyStore do AWS CloudHSM para o Client SDK 5 para encontrar chaves por rótulo. Para encontrar as chaves pelo manipulador, use AWS CloudHSM `KeyStoreWithAttributes` com AWS CloudHSM `KeyRefereneSpec`.
Descobrir várias entradas	Ao pesquisar por uma chave usando `getEntry`, `getKey` ou `getCertificate` em cenários com vários itens com os mesmos critérios no `Cavium` KeyStore, somente a primeira entrada encontrada será retornada.	Com AWS CloudHSM `KeyStore` e `KeyStoreWithAttributes`, esse mesmo cenário resultará em 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 CLI do CloudHSM 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 ter mais informações, consulte Gerencie com eficácia as chaves em seu aplicativo. Quando precisar recuperar todas as chaves do HSM, use `KeyStoreWithAttributes#getKeys` com um `KeyAttributesMap` vazio.	Um exemplo que usa a classe `KeyStoreWithAttributes`para encontrar uma chave está disponível no repositório de amostra do AWS CloudHSM Github e um trecho de código é mostrado em 1.
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 CloudHSM Github. Um trecho de amostra para cada SDK é mostrado em 2.

[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();
```

Mostrar mais

Mostrar menos

As operações de desencapsulamento de cifras foram alteradas, outras operações de cifragem não

nota

Nenhuma alteração é necessária nas operações de criptografia/descriptografia/encapsulamento do Cipher.

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

Mostrar mais

Mostrar menos

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.

Desinstalar o provedor JCE para o Client SDK 3.

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
```
nota
As configurações personalizadas precisam ser habilitadas novamente.
Instale o provedor JCE do Client SDK seguindo as etapas em Instalar e usar o provedor JCE para o Client SDK 5 do AWS CloudHSM.
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.
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

Práticas recomendadas do AWS CloudHSM

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

Migrar OpenSSL Dynamic Engine

Client SDK 5