Migre su JCE proveedor del AWS CloudHSM Cliente SDK 3 al Cliente SDK 5 - AWS CloudHSM
Prepárese abordando los cambios más importantesMigre al Cliente SDK 5Temas relacionados de

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Migre su JCE proveedor del AWS CloudHSM Cliente SDK 3 al Cliente SDK 5

Utilice este tema para migrar su JCEproveedor del AWS CloudHSM cliente SDK 3 al cliente SDK 5. Para obtener información sobre las ventajas de la migración, consulteVentajas del AWS CloudHSM cliente SDK 5.

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

El JCE proveedor del Cliente SDK 3 utiliza clases personalizadas APIs que no forman parte de la JCE especificación estándar. El cliente SDK 5 del JCE proveedor cumple con la JCE especificación y es incompatible con versiones anteriores del cliente SDK 3 en determinadas áreas. Las aplicaciones del cliente pueden requerir cambios como parte de la migración al Cliente SDK 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 AWS CloudHSM cliente SDK 3 al cliente 5 SDK.

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 el Cliente SDK 3 ¿Qué hay en el Cliente SDK 5 Ejemplo

Clase y nombre del proveedor

Se llama a la clase de JCE proveedor en el Cliente SDK 3 CaviumProvider y tiene el nombre de proveedorCavium.

En el cliente SDK 5, se llama a la clase Provider CloudHsmProvider y tiene el nombre ProviderCloudHSM.

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 el Cliente SDK 3 ¿Qué hay en el Cliente SDK 5 Ejemplo

Inicio de sesión explícito

El cliente SDK 3 usa la LoginManager clase para el inicio de sesión explícito 1.

En el cliente SDK 5, el CloudHSM proveedor implementa el inicio AuthProvider de sesión explícito. AuthProvideres 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 el Cliente SDK 5, las aplicaciones ya no necesitan monitorear ni iniciar sesión durante las reconexiones. 2

Para ver un ejemplo sobre cómo utilizar el inicio de sesión explícito con el Cliente SDK 5, consulta el LoginRunner ejemplo en el repositorio de HSM GitHub ejemplos de AWS Cloud.

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 Cliente SDK 3 al Cliente 5. SDK

Para ver un ejemplo sobre cómo utilizar el inicio de sesión implícito con el Cliente SDK 5, consulte el LoginRunner ejemplo en el AWS CloudHSM GitHub repositorio de ejemplos.

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

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

  • [2] Fragmento de código del cliente 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 el Cliente SDK 5, consulta el LoginRunner ejemplo en el repositorio de AWS CloudHSM GitHub ejemplos.

Mostrar másMostrar menos

La generación de claves ha cambiado

¿Qué ha cambiado ¿Qué había en el Cliente SDK 3 ¿Qué hay en el Cliente SDK 5 Ejemplo

Generación de claves

En el cliente 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 el cliente 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 sobre cómo se usa KeyAttributesMap para generar una clave simétrica, consulta el ejemplo en el repositorio de SymmetricKeys ejemplos de AWS Cloud HSM Github.

Generación de pares de claves

En el cliente SDK 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 el cliente 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 cliente 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 del cliente 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 del cliente 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 SDK 5 pares de claves del 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 másMostrar 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 cliente SDK 3 tiene dos KeyStore tipos: Cavium yCloudHSM. El cliente SDK 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 Cliente SDK 3 usa identificadores de teclas para hacer referencia a las claves, mientras que el Cliente SDK 5 usa etiquetas de teclas. Los cambios de comportamiento resultantes se enumeran a continuación.

¿Qué ha cambiado ¿Qué había en el Cliente SDK 3 ¿Qué hay en el Cliente SDK 5 Ejemplo

Referencias clave

Con el Cliente SDK 3, las aplicaciones utilizan etiquetas o identificadores de teclas para hacer referencia a las claves delHSM. Utilizan etiquetas KeyStore para encontrar una clave, o utilizan asas para crear CaviumKey objetos.

En Client SDK 5, las aplicaciones pueden usar el AWS CloudHSM KeyStore Clase Java para Client SDK 5 para buscar claves por etiqueta. Para buscar las llaves por asa, usa la tecla AWS CloudHSM KeyStoreWithAttributes con 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 yKeyStoreWithAttributes, en este mismo escenario, se generará una excepción. Para solucionar este problema, se recomienda establecer etiquetas únicas para las teclas mediante el Establece los atributos de las claves con Cloud HSM CLI comando de Cloud HSMCLI. O KeyStoreWithAttributes#getKeys utilízalas para devolver todas las claves que coincidan con los criterios.

Encuentra todas las claves

En el Cliente SDK 3 es posible encontrar todas las claves que se HSM utilizanUtil.findAllKeys().

El cliente 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 necesites recuperar todas las claves delHSM, úsalas KeyStoreWithAttributes#getKeys con una vacíaKeyAttributesMap.

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 cliente SDK 3 utiliza Util.deleteKey() para eliminar una clave.

El Key objeto del Cliente SDK 5 implementa la Destroyable interfaz que permite eliminar las claves mediante el destroy() método de esta interfaz.

Puedes encontrar un ejemplo de código que muestra la funcionalidad de eliminar claves en el repositorio de ejemplos de Cloud HSM Github. Se muestra un fragmento de muestra para cada una SDK de ellas 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 cliente SDK 3:

    Util.deleteKey(key);

    Eliminar una clave en el cliente SDK 5:

    ((Destroyable) key).destroy();
Mostrar másMostrar 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. encrypt/decrypt/wrap

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 másMostrar menos

Las operaciones de firma no han cambiado

No es necesario realizar cambios en las operaciones de firma.

Migre al Cliente SDK 5

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

nota

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

  1. Desinstale el JCE proveedor del Cliente SDK 3.

    Amazon Linux 2
    $ sudo yum remove cloudhsm-jce
    CentOS 7
    $ sudo yum remove cloudhsm-jce
    RHEL 7
    $ sudo yum remove cloudhsm-jce
    RHEL 8
    $ sudo yum remove cloudhsm-jce

  2. Desinstale el Client Daemon para el Cliente 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.

  3. Instale el SDK JCE proveedor de clientes siguiendo los pasos que se indican enInstale el JCE proveedor para el AWS CloudHSM cliente SDK 5.

  4. El cliente 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 JCE proveedor de Client SDK 5, siga las instrucciones que aparecen en la guía del usuario que aparece más abajo. Inicie el cliente SDK

  5. 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