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

Migre su proveedor de JCE de AWS CloudHSM Client SDK 3 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 del AWS CloudHSM cliente SDK 5.

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

El proveedor de JCE Client SDK 3 utiliza clases personalizadas APIs que no forman parte de la especificación JCE estándar. 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 del AWS CloudHSM cliente SDK 3 al cliente 5 SDK.

Temas

Preparación teniendo en cuenta los cambios más importantes
Migración 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`.	En el repositorio de muestras hay un ejemplo de cómo inicializar el `CloudHsmProvider`AWS CloudHSM GitHub objeto.

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 sobre cómo utilizar el inicio de sesión explícito con Client SDK 5, consulte el LoginRunner ejemplo en el repositorio de ejemplos de AWS GitHub CloudHSM.
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 el SDK de cliente 5, consulte el LoginRunner ejemplo en el AWS CloudHSM GitHub repositorio de ejemplos.

[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 sobre cómo utilizar el inicio de sesión explícito con Client SDK 5, consulta el LoginRunner ejemplo en el repositorio AWS CloudHSM GitHub de ejemplos.

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 `KeyAttributesMap` generar una clave simétrica, consulte el ejemplo en el repositorio de SymmetricKeys ejemplos de GitHub AWS CloudHSM.
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 utiliza `KeyAttributesMap` para generar una clave asimétrica, consulte el AsymmetricKeys ejemplo en el repositorio de ejemplos. AWS CloudHSM 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 AWS CloudHSM implica usar la KeyStore. El SDK 3 del cliente tiene dos KeyStore tipos: Cavium yCloudHSM. El SDK de cliente 5 solo tiene un KeyStore tipo:CloudHSM.

Pasar de un Cavium KeyStore a CloudHSM KeyStore otro requiere un cambio de KeyStore tipo. 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 KeyStore para encontrar una clave, o usan asas para crear `CaviumKey` objetos.	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 llaves por asa, usa la tecla AWS CloudHSM `KeyStoreWithAttributes` con AWS CloudHSM `KeyReferenceSpec`.
Buscar múltiples entradas	Al buscar una clave utilizando `getEntrygetKey`, o `getCertificate` en situaciones en las que existan varios elementos con el mismo criterio `Cavium` KeyStore, solo se devolverá la primera entrada encontrada.	Con la AWS CloudHSM `KeyStore` tecla y`KeyStoreWithAttributes`, en este mismo escenario, se generará una excepción. Para solucionar este problema, se recomienda establecer etiquetas únicas para las claves mediante el comando Establece los atributos de las claves con Cloud HSM CLI de la CLI de CloudHSM. O `KeyStoreWithAttributes#getKeys` utilícelo para devolver todas las claves que coincidan 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.	En el repositorio de muestras hay un ejemplo en el que se utiliza la `KeyStoreWithAttributes` clase para buscar una clave y en él se AWS CloudHSM GitHub muestra un fragmento de código. 1
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 que muestra la funcionalidad de eliminación de claves en el repositorio de ejemplos de GitHub CloudHSM. 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 es necesario realizar cambios en las operaciones de cifradoencrypt/decrypt/wrap.

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.

Migración 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 Instale el proveedor JCE para AWS CloudHSM Client SDK 5.
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 Inicie el cliente SDK.
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

Mejores prácticas 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

Migre el proveedor de almacenamiento de claves (KSP)

Cliente SDK 5