Preparación teniendo en cuenta los cambios más importantes Migrar a Client SDK 5 Temas relacionados de

Migrar su proveedor de JCE de Client SDK 3 de AWS CloudHSM a Client SDK 5

Use este tema para migrar su proveedor de JCE de Client SDK 3 del AWS CloudHSM a Client SDK 5. Para obtener información sobre las ventajas de la migración, consulte Ventajas de Client SDK 5 de AWS CloudHSM.

En AWS CloudHSM, las aplicaciones de los clientes realizan operaciones criptográficas mediante el kit de desarrollo de software (SDK) Client de AWS CloudHSM. Client SDK 5 es el SDK principal al que se le siguen agregando nuevas características y compatibilidad con plataformas.

El proveedor de JCE de Client SDK 3 usa clases y API personalizadas que no forman parte de la especificación estándar de la JCE. Client SDK 5 para el proveedor de JCE cumple con la especificación de JCE y, en determinadas áreas, es incompatible con versiones anteriores de Client SDK 3. Es posible que las aplicaciones del cliente requieran cambios como parte de la migración a Client SDK 5. En esta sección, se describen los cambios requeridos para que la migración se lleve a cabo correctamente.

Para revisar las instrucciones de migración de todos los proveedores, consulte Migración de Client SDK 3 de AWS CloudHSM a Client SDK 5.

Temas

Preparación teniendo en cuenta los cambios más importantes
Migrar a Client SDK 5
Temas relacionados de

Preparación teniendo en cuenta los cambios más importantes

Revise estos cambios importantes y actualice su aplicación en su entorno de desarrollo como corresponde.

La clase y el nombre del proveedor han cambiado

¿Qué ha cambiado?	Descripción anterior de Client SDK 3	Descripción actual de Client SDK 5	Ejemplo
Clase y nombre del proveedor	La clase de proveedor de JCE en Client SDK 3 se denomina `CaviumProvider` y tiene el nombre de proveedor `Cavium`.	En Client SDK 5, la clase de proveedor se denomina `CloudHsmProvider` y tiene el nombre de proveedor `CloudHSM`.	Presentamos un ejemplo de cómo inicializar el objeto `CloudHsmProvider` en el repositorio de muestras de AWS CloudHSM en GitHub.

El inicio de sesión explícito ha cambiado, pero el implícito no

¿Qué ha cambiado?	Descripción anterior de Client SDK 3	Descripción actual de Client SDK 5	Ejemplo
Inicio de sesión explícito	Client SDK 3 usa la clase `LoginManager` para el inicio de sesión explícito ¹.	En Client SDK 5, el proveedor de `CloudHSM` implementa `AuthProvider` para el inicio de sesión explícito. `AuthProvider` es una clase estándar de Java y sigue la forma idiomática de Java de iniciar sesión en un proveedor. Con la administración mejorada del estado de inicio de sesión en Client SDK 5, las aplicaciones ya no necesitan monitorear ni iniciar sesión durante las reconexiones².	Para ver un ejemplo de cómo usar el inicio de sesión explícito con Client SDK 5, consulte el ejemplo de LoginRunner en el repositorio de ejemplos de AWS CloudHSM en GitHub.
Inicio de sesión implícito	No se requieren cambios para el inicio de sesión implícito. El mismo archivo de propiedades y todas las variables de entorno seguirán funcionando para el inicio de sesión implícito al migrar de Client SDK 3 a Client SDK 5.		Para ver un ejemplo de cómo usar el inicio de sesión implícito con Client SDK 5, consulte el ejemplo de LoginRunner en el repositorio de ejemplos de AWS CloudHSM en GitHub.

[1] Fragmento de código de Client SDK 3:


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

[2] Fragmento de código de 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 un ejemplo de cómo usar el inicio de sesión explícito con Client SDK 5, consulte el ejemplo de LoginRunner en el repositorio de ejemplos de AWS CloudHSM en GitHub.

Mostrar menos

La generación de claves ha cambiado

¿Qué ha cambiado?	Descripción anterior de Client SDK 3	Descripción actual de Client SDK 5	Ejemplo
Generación de claves	En Client SDK 3, `Cavium[Key-type]AlgorithmParameterSpec` se usa para especificar los parámetros de generación de claves. Para ver un fragmento de código, consulte la nota a pie de página 1.	En Client SDK 5, `KeyAttributesMap` se usa para especificar los atributos de generación de claves. Para ver un fragmento de código, consulte la nota a pie de página 2.	Para ver un ejemplo de cómo se usa `KeyAttributesMap` para generar una clave simétrica, consulte el ejemplo de SymmetricKeys en el repositorio de ejemplos de AWS CloudHSM en GitHub.
Generación de pares de claves	En Client SDK 3, `Cavium[Key-type]AlgorithmparameterSpec` se usa para especificar los parámetros de generación de pares de claves. Para ver un fragmento de código, consulte la nota a pie de página 3.	En Client SDK 5, `KeyPairAttributesMap` se usa para especificar estos parámetros. Para ver un fragmento de código, consulte la nota a pie de página 4.	Para ver un ejemplo de cómo se usa `KeyAttributesMap` para generar una clave asimétrica, consulte el ejemplo de AsymmetricKeys en el repositorio de ejemplos de AWS CloudHSM en GitHub.

[1] Fragmento de código de generación de claves de 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] Fragmento de código de generación de claves de 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] Fragmento de código de generación de claves de 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] Fragmento de código de generación de claves de 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 menos

Se han modificado las claves de búsqueda, eliminación y referencia

Encontrar una clave ya generada con el AWS CloudHSM implica usar la KeyStore. Client SDK 3 tiene dos tipos de KeyStore: Cavium y CloudHSM. Client SDK 5 solo tiene un tipo de KeyStore: CloudHSM.

Para pasar de la KeyStore Cavium a la KeyStore CloudHSM, es necesario cambiar el tipo de KeyStore. Además, Client SDK 3 usa identificadores de claves para hacer referencia a las claves, mientras que Client SDK 5 usa etiquetas de clave. A continuación, se enumeran los cambios de comportamiento resultantes.

¿Qué ha cambiado?	Descripción anterior de Client SDK 3	Descripción actual de Client SDK 5	Ejemplo
Referencias de claves	Con Client SDK 3, las aplicaciones usan etiquetas o identificadores de claves para hacer referencia a las claves del HSM. Usan etiquetas con KeyStore para encontrar una clave, o bien, usan controladores y crean objetos `CaviumKey`.	En Client SDK 5, las aplicaciones pueden usar la Clase de Java KeyStore del AWS CloudHSM para Client SDK 5 para buscar claves por etiqueta. Para buscar las claves por identificador, use la `KeyStoreWithAttributes` del AWS CloudHSM with `KeyRefereneSpec` del AWS CloudHSM.
Buscar múltiples entradas	Al buscar una clave usando `getEntry`, `getKey` o `getCertificate` en situaciones en las que existan varios elementos con los mismos criterios en la KeyStore `Cavium`, solo se devolverá la primera entrada encontrada.	Con la `KeyStore` del AWS CloudHSM y `KeyStoreWithAttributes`, en esta situación, se hará una excepción. Para solucionar este problema, se recomienda establecer etiquetas únicas para las claves mediante el comando Establecimiento de los atributos de las claves con la CLI de CloudHSM de la CLI de CloudHSM. O bien, use `KeyStoreWithAttributes#getKeys` para devolver todas las claves que cumplan con los criterios.
Buscar todas las claves	En Client SDK 3, es posible buscar todas las claves del HSM usando `Util.findAllKeys()`.	Client SDK 5 simplifica y hace que la búsqueda de claves sea más sencilla y eficiente usando la clase `KeyStoreWithAttributes`. Cuando sea posible, almacene sus claves en caché para minimizar la latencia. Para obtener más información, consulte Gestione eficazmente las claves de su aplicación.. Cuando necesite recuperar todas las claves del HSM, use `KeyStoreWithAttributes#getKeys` con un `KeyAttributesMap` vacío.	Se presenta un ejemplo en el que se usa la clase `KeyStoreWithAttributes` para buscar una clave en el repositorio de muestras de AWS CloudHSM en Github y, en 1, se muestra un fragmento de código.
Eliminación de claves	Client SDK 3 usa `Util.deleteKey()` para eliminar una clave.	El objeto `Key` de Client SDK 5 implementa la interfaz `Destroyable`, que permite eliminar las claves mediante el método `destroy()` de esta interfaz.	Puede encontrar un código de ejemplo en el que se muestra la funcionalidad de eliminar claves en el repositorio de ejemplos de CloudHSM en GitHub. Se muestra un fragmento de código de muestra para cada SDK en 2.

[1] A continuación, se muestra un fragmento de código:


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] Eliminar una clave en Client SDK 3:
```
Util.deleteKey(key);
```
Eliminar una clave en Client SDK 5:
```
((Destroyable) key).destroy();
```

Mostrar menos

Las operaciones de desempaquetado de cifrado han cambiado, pero otras operaciones de cifrado no

nota

No se requiere realizar cambios en las operaciones de cifrado, descifrado ni empaquetado.

Las operaciones de desempaquetado requieren que la clase CaviumUnwrapParameterSpec de Client SDK 3 se sustituya por una de las siguientes clases específicas para las operaciones criptográficas enumeradas.

GCMUnwrapKeySpec para el desempaquetado de AES/GCM/NoPadding
IvUnwrapKeySpec para AESWrap unwrap y AES/CBC/NoPadding unwrap
OAEPUnwrapKeySpec para RSA OAEP unwrap

Ejemplo de fragmento de código 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 menos

Las operaciones de firma no han cambiado

No se requieren cambios en las operaciones de firma.

Migrar a Client SDK 5

Siga las instrucciones de esta sección para migrar de Client SDK 3 a Client SDK 5.

nota

Actualmente, Amazon Linux, Ubuntu 16.04, Ubuntu 18.04, CentOS 6, CentOS 8 y RHEL 6 no son compatibles con Client SDK 5. Si actualmente usa una de estas plataformas con Client SDK 3, tendrá que elegir una plataforma diferente al migrar a Client SDK 5.

Desinstale el proveedor de JCE para Client SDK 3.

Desinstale el daemon de cliente para 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
Es necesario volver a habilitar las configuraciones personalizadas.
Instale el proveedor de JCE de Client SDK siguiendo los pasos que se indican en Instalar el proveedor de JCE para Client SDK 5 del AWS CloudHSM.
Client SDK 5 presenta un nuevo formato de archivo de configuración y una nueva herramienta de arranque desde la línea de comandos. Para arrancar su proveedor de JCE para Client SDK 5, siga las instrucciones que se indican en la guía del usuario en Proceso de arranque del SDK de cliente.
Pruebe su aplicación en su entorno de desarrollo. Actualice el código existente para resolver los cambios importantes antes de la migración final.

Temas relacionados de

Prácticas recomendadas para AWS CloudHSM

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Migrar el motor dinámico de OpenSSL

SDK 5 de cliente