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

Migre seu provedor de JCE do Client SDK 3 para o Client SDK 5

Use este tópico para migrar seu provedor de JCE do SDK do cliente 3 para o SDK do cliente 5. Para obter os benefícios da migração, consulteBenefícios do Client SDK 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 continua a ter novos recursos e suporte de plataforma adicionados a ele.

O provedor Client SDK 3 JCE usa classes e APIs personalizadas que não fazem parte da especificação JCE padrão. O SDK 5 do cliente para o provedor JCE está em conformidade com a especificação JCE e é incompatível com versões anteriores do SDK do cliente 3 em determinadas áreas. Os aplicativos 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, consulteMigração do Client SDK 3 para o Client SDK 5.

Tópicos

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

Prepare-se abordando as mudanças mais importantes

Analise essas alterações importantes e atualize seu aplicativo 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 `CaviumProvider` e tem o nome do provedor. `Cavium`	No Client SDK 5, a classe Provider é chamada `CloudHsmProvider` e tem o nome `CloudHSM` Provider.	Um exemplo de como inicializar o `CloudHsmProvider` objeto está disponível no repositório de AWS CloudHSM GitHub amostra.

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 SDK 3 do cliente usa a `LoginManager` classe para login explícito. ¹	No Client SDK 5, o `CloudHSM` provedor implementa o login `AuthProvider` 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, os aplicativos 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 o LoginRunner exemplo no repositório de amostras do AWS GitHub CloudHSM.
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 SDK do cliente 3 para o SDK do cliente 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 de amostras.

[1] Trecho de código do SDK 3 do cliente:


LoginManager lm = LoginManager.getInstance();
                       
lm.login(partition, user, pass);

[2] Trecho de código do SDK 5 do cliente:


// 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 de amostras.

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 SymmetricKeys amostra 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 AsymmetricKeys amostra no repositório de AWS CloudHSM GitHub amostras.

[1] Trecho de código de geração de chave 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 chave 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 5 pares de chaves do SDK do cliente:


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 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 referenciar chaves, enquanto o Client SDK 5 usa rótulos de chave. As mudanças de comportamento resultantes estão listadas abaixo.

O que mudou	O que estava no Client SDK 3	O que está no Client SDK 5	Exemplo
Referências principais	Com o Client SDK 3, os aplicativos usam rótulos ou identificadores de teclas para referenciar 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, os aplicativos podem usar o Usando a classe AWS CloudHSM KeyStore Java para encontrar chaves por rótulo. Para encontrar as chaves pela alça, use o AWS CloudHSM `KeyStoreWithAttributes` com AWS CloudHSM `KeyRefereneSpec`.
Encontrando 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 atributo do conjunto de chaves comando na CLI do CloudHSM. Ou use `KeyStoreWithAttributes#getKeys` para retornar todas as chaves que correspondam aos critérios.
Encontre todas as chaves	É possível no Client SDK 3 encontrar todas as chaves no HSM usando. `Util.findAllKeys()`	O SDK 5 do cliente torna a localização de chaves mais simples e eficiente usando a `KeyStoreWithAttributes` classe. 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 vazio. `KeyAttributesMap`	Um exemplo que usa a `KeyStoreWithAttributes` classe 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 SDK 3 do cliente usa `Util.deleteKey()` para excluir uma chave.	O `Key` objeto no Client SDK 5 implementa a `Destroyable` interface que permite que as chaves sejam excluídas usando o `destroy()` método 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 do CloudHSM. 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] Excluindo uma chave no SDK do cliente 3:
```
Util.deleteKey(key);
```
Excluindo uma chave no Client SDK 5:
```
((Destroyable) key).destroy();
```

Mostrar mais

Mostrar menos

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

nota

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

As operações de desempacotamento exigem que a CaviumUnwrapParameterSpec classe Client SDK 3 seja substituída por uma das seguintes classes específicas das operações criptográficas listadas.

GCMUnwrapKeySpecpara AES/GCM/NoPadding desembrulhar
IvUnwrapKeySpecpara AESWrap unwrap e AES/CBC/NoPadding unwrap
OAEPUnwrapKeySpec para RSA OAEP unwrap

Exemplo de trecho 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 nas operações de assinatura.

Migrar para o Client SDK 5

Siga as instruções nesta seção para migrar do SDK do cliente 3 para o SDK do cliente 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.

Desinstale o provedor JCE para o Client SDK 3.

Desinstale o daemon do cliente para o SDK do cliente 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 ativadas novamente.
Instale o provedor JCE do SDK do cliente seguindo as etapas em. Instale e use o provedor AWS CloudHSM JCE para o Client SDK 5
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 do Client SDK 5 JCE, siga as instruções listadas no guia do usuário abaixo. Bootstrap o Client SDK
Em seu ambiente de desenvolvimento, teste seu aplicativo. Faça atualizações em seu código existente para resolver suas alterações importantes antes da migração final.

Tópicos relacionados

Melhores práticas para 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

CloudHSM KeyStore

Configurações avançadas