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

Modo de foco

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

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

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 AWS CloudHSM 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 sempre recebe novos recursos 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.

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 `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 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 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 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 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 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.	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 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.	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 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 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 CLI do CloudHSM na CLI do CloudHSM. Ou use `KeyStoreWithAttributes#getKeys` para retornar todas as chaves que correspondam 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. 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 e um trecho de código é exibido 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 GitHub 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] 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.

Desinstalar o provedor JCE para o Client SDK 3.

anchor anchor anchor anchor


$ sudo yum remove cloudhsm-client-jce

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
```
anchor anchor anchor anchor
$ 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 Instale o provedor JCE para o AWS CloudHSM 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 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

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

Migrar provedor de armazenamento de chaves (KSP)

Client SDK 5

Nesta página

Selecione suas preferências de cookies

Personalizar preferências de cookies

Essenciais

Desempenho

Funcionais

Publicidade

Não foi possível salvar as preferências de cookie

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

Tópicos

Preparar-se abordando as mudanças mais importantes

A classe e o nome do provedor foram alterados

O login explícito foi alterado, o implícito não

A geração de chaves mudou

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

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

nota

As operações de assinatura não foram alteradas

Migrar para o Client SDK 5

nota

nota

Tópicos relacionados

Nesta página

Esta página foi útil?

Próximo tópico:

Tópico anterior:

Precisa de ajuda?