Prepárese abordando los cambios más importantes Migre al SDK 5 de cliente Temas relacionados de

Migre su proveedor de JCE de Client SDK 3 a Client SDK 5

Utilice este tema para migrar su proveedor de JCE del SDK de cliente 3 al SDK de cliente 5. Para obtener información sobre las ventajas de la migración, consulte. Ventajas del SDK 5 de cliente

En AWS CloudHSM, las aplicaciones de los clientes realizan operaciones criptográficas mediante el kit de desarrollo de software (SDK) para AWS CloudHSM clientes. El SDK de cliente 5 es el SDK principal al que se le siguen añadiendo nuevas funciones y compatibilidad con plataformas.

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

Para revisar las instrucciones de migración de todos los proveedores, consulteMigración del SDK 3 de cliente al SDK 5 de cliente.

Temas

Prepárese abordando los cambios más importantes
Migre al SDK 5 de cliente
Temas relacionados de

Prepárese abordando los cambios más importantes

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

La clase y el nombre del proveedor han cambiado

¿Qué ha cambiado	¿Qué había en Client SDK 3	¿Qué hay en Client SDK 5	Ejemplo
Clase y nombre del proveedor	Se llama a la clase de proveedor JCE en Client SDK 3 `CaviumProvider` y tiene el nombre `Cavium` de proveedor.	En el SDK de cliente 5, se llama a la clase Provider `CloudHsmProvider` y tiene el nombre `CloudHSM` de proveedor.	En el repositorio de AWS CloudHSM GitHub muestras hay un ejemplo de cómo inicializar el `CloudHsmProvider` objeto.

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

¿Qué ha cambiado	¿Qué había en Client SDK 3	¿Qué hay en Client SDK 5	Ejemplo
Inicio de sesión explícito	El SDK 3 del cliente usa la `LoginManager` clase para el inicio de sesión explícito ¹.	En el SDK de cliente 5, el `CloudHSM` proveedor implementa el inicio `AuthProvider` 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 es necesario realizar 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 del SDK de cliente 3 al SDK de cliente 5.		Para ver un ejemplo sobre cómo usar el inicio de sesión implícito con Client SDK 5, consulta el LoginRunner ejemplo en el AWS CloudHSM GitHub repositorio de ejemplos.

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


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

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

Mostrar menos

La generación de claves ha cambiado

¿Qué ha cambiado	¿Qué había en Client SDK 3	¿Qué hay en Client SDK 5	Ejemplo
Generación de claves	En Client SDK 3, `Cavium[Key-type]AlgorithmParameterSpec` se utiliza 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 utiliza 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 utiliza `KeyAttributesMap` para generar una clave simétrica, consulte el ejemplo en el repositorio de SymmetricKeys muestras de Github de AWS CloudHSM.
Generación de pares de claves	En el SDK de cliente 3, `Cavium[Key-type]AlgorithmparameterSpec` se utiliza 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 utiliza 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 sobre cómo `KeyAttributesMap` generar una clave asimétrica, consulta el ejemplo en el repositorio de AsymmetricKeys ejemplos. AWS CloudHSM GitHub

[1] Fragmento de código de generación de claves del SDK 3 de Client:


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 del 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 pares 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 5 pares de claves del SDK de 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 menos

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

Para encontrar una clave ya generada, se AWS CloudHSM debe utilizar 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, el SDK de cliente 3 usa identificadores de teclas para hacer referencia a las claves, mientras que el SDK de cliente 5 usa etiquetas de clave. Los cambios de comportamiento resultantes se muestran a continuación.

¿Qué ha cambiado	¿Qué había en Client SDK 3	¿Qué hay en Client SDK 5	Ejemplo
Referencias clave	Con Client SDK 3, las aplicaciones utilizan etiquetas o identificadores de teclas para hacer referencia a las claves del HSM. Utilizan etiquetas KeyStore para encontrar una clave o utilizan identificadores para crear `CaviumKey` objetos.	En Client SDK 5, las aplicaciones pueden Uso de la clase AWS CloudHSM KeyStore Java utilizarla para buscar claves por etiqueta. Para buscar las claves por identificador, usa la tecla AWS CloudHSM `KeyStoreWithAttributes` with AWS CloudHSM `KeyRefereneSpec`.
Búsqueda de múltiples entradas	Al buscar una clave utilizando `getEntrygetKey`, o `getCertificate` en situaciones en las que existan varios elementos con los mismos criterios `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 key set-attribute comando de la CLI de CloudHSM. O `KeyStoreWithAttributes#getKeys` utilícelas para devolver todas las claves que coincidan con los criterios.
Encuentra todas las claves	En el SDK de cliente 3 es posible encontrar todas las claves del HSM utilizando`Util.findAllKeys()`.	El Client SDK 5 simplifica y hace más eficiente la búsqueda de claves mediante el uso de la `KeyStoreWithAttributes` clase. 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, utilícelas `KeyStoreWithAttributes#getKeys` con una vacía`KeyAttributesMap`.	Un ejemplo en el que se usa la `KeyStoreWithAttributes` clase para buscar una clave está disponible en el repositorio de muestras de AWS CloudHSM Github y en él se muestra un fragmento de código. 1
Eliminación de claves	El SDK de cliente 3 se usa `Util.deleteKey()` para eliminar una clave.	El `Key` objeto del Client SDK 5 implementa la `Destroyable` interfaz que permite eliminar las claves mediante el `destroy()` método de esta interfaz.	Puede encontrar un código de ejemplo que muestra la funcionalidad de eliminar claves en el repositorio de ejemplos de GitHub de CloudHSM. Se muestra un fragmento de muestra para cada SDK en. 2

[1] A continuación se muestra un fragmento:


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

Mostrar menos

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

nota

No es necesario realizar cambios en las operaciones de cifrado, descifrado y empaquetado de Cipher.

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

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

Fragmento de ejemplo 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 es necesario realizar cambios en las operaciones de firma.

Migre al SDK 5 de cliente

Siga las instrucciones de esta sección para migrar del SDK de cliente 3 al SDK de cliente 5.

nota

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

Desinstale el proveedor de JCE para Client SDK 3.

Desinstale el Client Daemon 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 JCE del SDK de cliente siguiendo los pasos que se indican. Instalar y usar el proveedor AWS CloudHSM JCE para Client SDK 5
El 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 iniciar su proveedor de JCE para el SDK 5 de Client, siga las instrucciones que se indican en la guía del usuario que aparece a continuación. Proceso de arranque del SDK de cliente
En su entorno de desarrollo, pruebe la aplicación. 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

ClouDHSM KeyStore

Configuraciones avanzadas