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. # Migración del SDK de AWS CloudHSM cliente 3 al SDK de cliente 5 En AWS CloudHSM, las aplicaciones de los clientes 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. Client SDK 3 incluye dos herramientas de la línea de comandos independientes: la CMU para administrar usuarios y la KMU para administrar claves y realizar operaciones con ellas. Client SDK 5 consolida las funciones de la CMU y la KMU (herramientas que se ofrecían con Client SDK 3) en una sola herramienta, la [AWS CloudHSM Interfaz de línea de comandos (CLI)](cloudhsm_cli.md). Las operaciones de administración de usuarios se encuentran en los subcomandos [La categoría de usuario en la CLI de CloudHSM](cloudhsm_cli-user.md) y [La categoría de token en la CLI de CloudHSM](cloudhsm_cli-qm.md). Las operaciones de administración de claves se encuentran en el [subcomando key](cloudhsm_cli-key.md) y las operaciones criptográficas, en el [subcomando crypto](cloudhsm_cli-crypto.md). Para ver una lista completa de comandos, consulte [Referencia para los comandos de la CLI de CloudHSM](cloudhsm_cli-reference.md). Para obtener información sobre la migración, consulte [Ventajas del SDK 5 para AWS CloudHSM clientes](client-sdk-5-benefits.md). Consulte los siguientes temas para obtener instrucciones detalladas sobre la migración del SDK de cliente 3 al SDK de cliente 5. La última versión del SDK de AWS CloudHSM cliente es la 5.16. + [Migre su biblioteca AWS CloudHSM PKCS \$111 del SDK de cliente 3 al SDK de cliente 5](pkcs11-migrate-to-sdk-5.md) + [Migre su motor dinámico OpenSSL del Client SDK 3 AWS CloudHSM al Client SDK 5](openssl-migrate-to-sdk-5.md) + [Migre su proveedor de almacenamiento de claves (KSP) del SDK de AWS CloudHSM cliente 3 al SDK de cliente 5](ksp-migrate-to-sdk-5.md) + [Migre su proveedor de JCE de AWS CloudHSM Client SDK 3 a Client SDK 5](java-lib-migrate_to_sdk5.md) Para funcionalidades o casos de uso no compatibles con la CLI de CloudHSM, póngase en contacto con [AWS Support](https://support.console.aws.amazon.com/support/home#/). # Migre su biblioteca AWS CloudHSM PKCS \$111 del SDK de cliente 3 al SDK de cliente 5 Utilice este tema para migrar la [biblioteca AWS CloudHSM PKCS \$111](pkcs11-library.md) del SDK de cliente 3 al SDK de cliente 5. Para obtener información sobre la migración, consulte [Ventajas del SDK 5 para AWS CloudHSM clientes](client-sdk-5-benefits.md). 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. Para revisar las instrucciones de migración de todos los proveedores, consulte [Migración del SDK de AWS CloudHSM cliente 3 al SDK de cliente 5](client-sdk-migration.md). ## 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. ### Los mecanismos de empaquetado han cambiado **** | Mecanismo de Client SDK 3 | Mecanismo equivalente de Client SDK 5 | | --- | --- | | `CKM_AES_KEY_WRAP` | `CKM_CLOUDHSM_AES_KEY_WRAP_PKCS5_PAD` | | `CKM_AES_KEY_WRAP_PAD` | `CKM_CLOUDHSM_AES_KEY_WRAP_ZERO_PAD` | | `CKM_CLOUDHSM_AES_KEY_WRAP_PKCS5_PAD` | `CKM_CLOUDHSM_AES_KEY_WRAP_PKCS5_PAD` | | `CKM_CLOUDHSM_AES_KEY_WRAP_NO_PAD` | `CKM_CLOUDHSM_AES_KEY_WRAP_NO_PAD` | | `CKM_CLOUDHSM_AES_KEY_WRAP_ZERO_PAD` | `CKM_CLOUDHSM_AES_KEY_WRAP_ZERO_PAD` | ### ECDH En Client SDK 3, puede usar el ECDH y especificar un KDF. Esta funcionalidad no está disponible actualmente en Client SDK 5. Si su aplicación necesita esta funcionalidad, comuníquese con el [servicio de asistencia](https://support.console.aws.amazon.com/support/home#/). ### Los identificadores de claves ahora son específicos de cada sesión Para utilizar correctamente los identificadores de clave en SDK 5 de cliente, debe obtener los identificadores de clave cada vez que ejecute una aplicación. Si tiene aplicaciones existentes que usarán los mismos identificadores de clave en distintas sesiones, debe modificar el código para obtener el identificador de clave cada vez que ejecute la aplicación. Para obtener información sobre la recuperación de identificadores de claves, consulte [este ejemplo del AWS CloudHSM PKCS \$111.](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/find_objects/find_objects.c) Este cambio cumple con la especificación [PKCS \$111 2.40](http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html#_Toc416959689). ## 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. 1. Desinstale la biblioteca PKCS \$111 para Client SDK 3. ------ #### [ Amazon Linux 2 ] ``` $ sudo yum remove cloudhsm-client-pkcs11 ``` ------ #### [ CentOS 7 ] ``` $ sudo yum remove cloudhsm-client-pkcs11 ``` ------ #### [ RHEL 7 ] ``` $ sudo yum remove cloudhsm-client-pkcs11 ``` ------ #### [ RHEL 8 ] ``` $ sudo yum remove cloudhsm-client-pkcs11 ``` ------ #### [ Ubuntu 16.04 LTS ] ``` $ sudo apt remove cloudhsm-client-pkcs11 ``` ------ #### [ Ubuntu 18.04 LTS ] ``` $ sudo apt remove cloudhsm-client-pkcs11 ``` ------ 1. Detenga el daemon de cliente para el SDK de cliente 3. ------ #### [ Amazon Linux 2 ] ``` $ sudo service cloudhsm-client stop ``` ------ #### [ CentOS 7 ] ``` $ sudo service cloudhsm-client stop ``` ------ #### [ RHEL 7 ] ``` $ sudo service cloudhsm-client stop ``` ------ #### [ RHEL 8 ] ``` $ sudo service cloudhsm-client stop ``` ------ #### [ Ubuntu 16.04 LTS ] ``` $ sudo systemctl stop cloudhsm-client ``` ------ #### [ Ubuntu 18.04 LTS ] ``` $ sudo systemctl stop cloudhsm-client ``` ------ 1. 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 ``` ------ #### [ Ubuntu 16.04 LTS ] ``` $ sudo apt remove cloudhsm-client ``` ------ #### [ Ubuntu 18.04 LTS ] ``` $ sudo apt remove cloudhsm-client ``` ------ **nota** Es necesario volver a habilitar las configuraciones personalizadas. 1. Instale la biblioteca PKCS \$111 de Client SDK siguiendo los pasos que se indican en [Instale la biblioteca PKCS \$111 para el SDK de AWS CloudHSM cliente 5](pkcs11-library-install.md). 1. 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 biblioteca PKCS \$111 para Client SDK 5, siga las instrucciones que se indican en la guía del usuario en [Proceso de arranque del SDK de cliente](cluster-connect.md#connect-how-to). 1. 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 + [Mejores prácticas para AWS CloudHSM](best-practices.md) # Migre su motor dinámico OpenSSL del Client SDK 3 AWS CloudHSM al Client SDK 5 Use este tema para migrar su [motor dinámico de OpenSSL](openssl-library.md) de Client SDK 3 de AWS CloudHSM a Client SDK 5. Para obtener información sobre la migración, consulte [Ventajas del SDK 5 para AWS CloudHSM clientes](client-sdk-5-benefits.md). 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. **nota** La generación de números aleatorios no se admite actualmente en Client SDK 5 con el motor dinámico de OpenSSL. Para revisar las instrucciones de migración de todos los proveedores, consulte [Migración del SDK de AWS CloudHSM cliente 3 al SDK de cliente 5](client-sdk-migration.md). ## 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. 1. Desinstale el motor dinámico de OpenSSL para Client SDK 3. ------ #### [ Amazon Linux 2 ] ``` $ sudo yum remove cloudhsm-client-dyn ``` ------ #### [ CentOS 7 ] ``` $ sudo yum remove cloudhsm-client-dyn ``` ------ #### [ RHEL 7 ] ``` $ sudo yum remove cloudhsm-client-dyn ``` ------ #### [ RHEL 8 ] ``` $ sudo yum remove cloudhsm-client-dyn ``` ------ #### [ Ubuntu 16.04 LTS ] ``` $ sudo apt remove cloudhsm-client-dyn ``` ------ #### [ Ubuntu 18.04 LTS ] ``` $ sudo apt remove cloudhsm-client-dyn ``` ------ 1. Detenga el daemon de cliente para el SDK de cliente 3. ------ #### [ Amazon Linux 2 ] ``` $ sudo service cloudhsm-client stop ``` ------ #### [ CentOS 7 ] ``` $ sudo service cloudhsm-client stop ``` ------ #### [ RHEL 7 ] ``` $ sudo service cloudhsm-client stop ``` ------ #### [ RHEL 8 ] ``` $ sudo service cloudhsm-client stop ``` ------ #### [ Ubuntu 16.04 LTS ] ``` $ sudo systemctl stop cloudhsm-client ``` ------ #### [ Ubuntu 18.04 LTS ] ``` $ sudo systemctl stop cloudhsm-client ``` ------ 1. 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 ``` ------ #### [ Ubuntu 16.04 LTS ] ``` $ sudo apt remove cloudhsm-client ``` ------ #### [ Ubuntu 18.04 LTS ] ``` $ sudo apt remove cloudhsm-client ``` ------ **nota** Es necesario volver a habilitar las configuraciones personalizadas. 1. Instale el motor dinámico de OpenSSL de Client SDK siguiendo los pasos que se indican en [Instalación del motor AWS CloudHSM dinámico OpenSSL para el SDK 5 del cliente](openssl5-install.md). 1. 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 motor dinámico de OpenSSL en Client SDK 5, siga las instrucciones que se indican en la guía del usuario en [Proceso de arranque del SDK de cliente](cluster-connect.md#connect-how-to). 1. 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 + [Mejores prácticas para AWS CloudHSM](best-practices.md) # Migre su proveedor de almacenamiento de claves (KSP) del SDK de AWS CloudHSM cliente 3 al SDK de cliente 5 En este tema, se explica cómo migrar el [proveedor de almacenamiento de claves (KSP)](ksp-library.md) del SDK de cliente 3 al SDK de cliente 5 de AWS CloudHSM . La versión más reciente del SDK de AWS CloudHSM cliente es la 5.16. Para obtener información sobre los beneficios de la migración, consulte [Ventajas del SDK 5 para AWS CloudHSM clientes](client-sdk-5-benefits.md). En AWS CloudHSM, se utiliza el kit de desarrollo de software (SDK) de AWS CloudHSM cliente para realizar operaciones criptográficas. El SDK de cliente 5 es el SDK principal que recibe nuevas características y actualizaciones de compatibilidad con la plataforma. Para consultar las instrucciones de migración para todos los proveedores, consulte [Migración del SDK de AWS CloudHSM cliente 3 al SDK de cliente 5](client-sdk-migration.md). ## Migración a Client SDK 5 1. Detenga el daemon de cliente para el SDK de cliente 3. ``` PS C:\> Stop-Service "AWS CloudHSM Client" ``` 1. Instale el proveedor de almacenamiento de claves (KSP) del SDK de cliente 5 en la instancia de Windows Server. Para obtener instrucciones, consulte [Instale el proveedor de almacenamiento de claves (KSP) para el SDK AWS CloudHSM 5 del cliente](ksp-library-install.md). 1. Configure el proveedor de almacenamiento de claves (KSP) del SDK de cliente 5 mediante el nuevo formato de archivo de configuración y la herramienta de inicialización por línea de comandos. Para obtener instrucciones, consulte [Proceso de arranque del SDK de cliente](cluster-connect.md#connect-how-to). 1. El proveedor de almacenamiento de claves (KSP) para AWS CloudHSM Client SDK 5 incluye un modo de SDK3 compatibilidad para admitir los archivos de referencia clave generados en él. SDK3 Para obtener más información, consulte [SDK3 modo de compatibilidad para el proveedor de almacenamiento de claves (KSP) para AWS CloudHSM](ksp-library-configs-sdk3-compatibility-mode.md). **nota** Debe habilitar el modo de SDK3 compatibilidad cuando utilice los archivos de referencia clave generados por el SDK de cliente 3 con el SDK de cliente 5. ## Migración a nuevas instancias de Windows Server 1. Complete todos los pasos que se indican en [Migración al SDK de cliente 5](#ksp-migrate-steps) en las nuevas instancias de Windows Server. 1. **Cómo comprobar la existencia de archivos de referencia de claves** En la instancia original de Windows Server, compruebe la existencia de archivos de referencia de claves en `C:\Users\Default\AppData\Roaming\Microsoft\Crypto\CaviumKSP\GlobalPartition`. + Si existen archivos de referencia de claves, copie todo el contenido bajo `C:\Users\Default\AppData\Roaming\Microsoft\Crypto\CaviumKSP`, incluido `GlobalPartition`, en la misma ruta de directorio de la nueva instancia de Windows Server. Cree el directorio si no existe. + Si no existen archivos de referencia de claves, use `cloudhsm-cli key generate-file --encoding ksp-key-reference` en la nueva instancia de Windows Server para crearlos. Para obtener instrucciones, consulte [Generación de referencias de claves KSP (Windows)](cloudhsm_cli-key-generate-file.md#key-generate-ksp-key-reference). 1. **Verificación del certificado raíz** Revise el certificado raíz en las autoridades de certificación raíz confiables: ``` PS C:\Users\Administrator\Desktop> certutil -store Root Root "Trusted Root Certification Authorities" ================ Certificate 0 ================ Serial Number: certificate-serial-number Issuer: CN=MYRootCA NotBefore: 2/5/2020 1:38 PM NotAfter: 2/5/2021 1:48 PM Issuer: CN=MYRootCA Signature matches Public Key Root Certificate: Subject matches Issuer Cert Hash(sha1): cert-hash No key provider information Cannot find the certificate and private key for decryption. CertUtil: -store command completed successfully. ``` **nota** Anote el número de serie del certificado para usarlo en el siguiente paso. 1. **Exportación del certificado raíz** Exportar el certificado raíz a un archivo: ``` certutil -store Root certificate-serial-number root-certificate-name.cer ``` 1. **Verificación del certificado de backend HSM** Revise el certificado de backend HSM en el almacén de certificados personales. ``` PS C:\Users\Administrator\Desktop> certutil -store My my "Personal" ================ Certificate 0 ================ Serial Number: certificate-serial-number Issuer: CN=MYRootCA NotBefore: 2/5/2020 1:38 PM NotAfter: 2/5/2021 1:48 PM Subject: CN=www.mydomain.com, OU=Certificate Management, O=Information Technology, L=Houston, S=Texas, C=US Non-root Certificate Cert Hash(sha1): cert-hash Key Container = key-container-name Provider = Cavium Key Storage Provider Private key is NOT exportable Encryption test passed CertUtil: -store command completed successfully. ``` **nota** Anote el número de serie del certificado para usarlo en el siguiente paso. 1. **Exportación del certificado de backend HSM** Exportar el certificado de backend HSM a un archivo: ``` certutil -store My certificate-serial-number signed-certificate-name.cer ``` 1. **Importación del certificado raíz** En la nueva instancia de Windows: 1. Copie el archivo CA raíz a la nueva instancia de Windows 1. Importe el certificado: ``` certutil -addstore Root root-certificate-name.cer ``` 1. **Verificación de la instalación del certificado raíz** Confirme que el certificado raíz esté correctamente instalado. ``` PS C:\Users\Administrator\Desktop> certutil -store Root Root "Trusted Root Certification Authorities" ================ Certificate 0 ================ Serial Number: certificate-serial-number Issuer: CN=MYRootCA NotBefore: 2/5/2020 1:38 PM NotAfter: 2/5/2021 1:48 PM Issuer: CN=MYRootCA Signature matches Public Key Root Certificate: Subject matches Issuer Cert Hash(sha1): cert-hash No key provider information Cannot find the certificate and private key for decryption. CertUtil: -store command completed successfully. ``` 1. **Importación del certificado de backend HSM** En la nueva instancia de Windows: 1. Copie el certificado de backend HSM en la nueva instancia de Windows 1. Importe el certificado: ``` certutil -addstore My signed-certificate-name.cer ``` 1. **Verificación de la instalación del certificado de backend HSM** Confirme que el certificado de backend HSM esté correctamente instalado: ``` PS C:\Users\Administrator\Desktop> certutil -store My my "Personal" ================ Certificate 0 ================ Serial Number: certificate-serial-number Issuer: CN=MYRootCA NotBefore: 2/5/2020 1:38 PM NotAfter: 2/5/2021 1:48 PM Subject: CN=www.mydomain.com, OU=Certificate Management, O=Information Technology, L=Houston, S=Texas, C=US Non-root Certificate Cert Hash(sha1): cert-hash No key provider information Cannot find the certificate and private key for decryption. CertUtil: -store command completed successfully. ``` **nota** Anote el número de serie del certificado para usarlo en los pasos posteriores. 1. **Creación de un archivo de referencia de claves (opcional)** Complete este paso solo si necesita crear un nuevo archivo de referencia de claves. De lo contrario, continúe con el próximo paso. **nota** Esta característica solo está disponible en la versión 5.16.0 del SDK y posteriores. 1. Instale [OpenSSL](https://slproweb.com/products/Win32OpenSSL.html) y extraiga el módulo: ``` openssl x509 -in signed-certificate-name.cer -modulus -noout ``` **nota** El comando de OpenSSL genera el módulo en el formato: `Modulus=modulus-value`. Anote *modulus-value* esto para usarlo en el siguiente comando. 1. Creación del archivo de referencia de claves con la CLI de CloudHSM. Consulte [Generación de referencias de claves KSP (Windows)](cloudhsm_cli-key-generate-file.md#key-generate-ksp-key-reference): ``` & "C:\Program Files\Amazon\CloudHSM\bin\cloudhsm-cli.exe" key generate-file --encoding ksp-key-reference --filter attr.class=private-key attr.modulus=0xmodulus-value ``` **nota** Los *modulus-value* argumentos del comando CLI de CloudHSM deben ir precedidos de un `0x` prefijo para indicar el formato hexadecimal. Los archivos de referencia de claves se crean en `C:\Users\Default\AppData\Roaming\Microsoft\Crypto\CaviumKSP\GlobalPartition`. 1. **Creación de la configuración de reparación** Cree un archivo denominado `repair.txt` con el siguiente contenido: ``` [Properties] 11 = "" ; Add friendly name property 2 = "{text}" ; Add Key Provider Information property _continue_="Container=key-container-name&" _continue_="Provider=Cavium Key Storage Provider&" _continue_="Flags=0&" _continue_="KeySpec=2" ``` **nota** *key-container-name*Sustitúyalos por el nombre de archivo de referencia clave de. `C:\Users\Default\AppData\Roaming\Microsoft\Crypto\CaviumKSP\GlobalPartition` 1. **Reparación del almacén de certificados** Ejecute el comando de reparación: ``` certutil -repairstore My certificate-serial-number repair.txt ``` **nota** El número de serie del certificado se obtiene en los pasos anteriores al verificar la instalación del certificado de backend HSM. 1. **Verificación de la asociación del certificado.** Confirme que el certificado esté correctamente asociado: ``` PS C:\Users\Administrator\Desktop> certutil -store My my "Personal" ================ Certificate 0 ================ Serial Number: certificate-serial-number Issuer: CN=MYRootCA NotBefore: 2/5/2020 1:38 PM NotAfter: 2/5/2021 1:48 PM Subject: CN=www.mydomain.com, OU=Certificate Management, O=Information Technology, L=Houston, S=Texas, C=US Non-root Certificate Cert Hash(sha1): cert-hash Key Container = key-container-name Provider = Cavium Key Storage Provider Private key is NOT exportable ERROR: Could not verify certificate public key against private key CertUtil: -store command completed successfully. ``` Verifique que la salida muestre: + El nombre correcto del contenedor de claves + El proveedor de almacenamiento de claves Cavium + `ERROR: Could not verify certificate public key against private key` se trata de un problema conocido. Consulte [Problema: ña verificación de un almacén de certificados falla](ki-ksp-sdk.md#ki-ksp-1) 1. **Prueba de la aplicación** Antes de completar la migración: 1. Pruebe la aplicación en el entorno de desarrollo 1. Actualice el código para resolver cualquier cambio incompatible 1. Para obtener orientación específica de la aplicación, consulte [Integración de aplicaciones de terceros con AWS CloudHSM](third-party-applications.md) ## Verificación de la migración Después de completar los pasos de migración, verifique que: + Los certificados estén correctamente instalados en los almacenes de certificados correctos + Los archivos de referencia de claves estén presentes en la ubicación correcta + La aplicación pueda realizar operaciones criptográficas con los certificados migrados ## Resolución de problemas Si tiene problemas durante la migración, compruebe lo siguiente: + Todos los certificados se hayan exportado correctamente del sistema de origen + Los números de serie de los certificados coincidan entre los sistemas + Los nombres de los contenedores de claves en el archivo repair.txt coincidan con los archivos de referencia de claves + SDK3 el modo de compatibilidad está activado si se utilizan archivos SDK3 de referencia clave generados por ellos ## Temas relacionados + [Mejores prácticas para AWS CloudHSM](best-practices.md) # Migre su proveedor de JCE de AWS CloudHSM Client SDK 3 a Client SDK 5 Use este tema para migrar su [proveedor de JCE](java-library.md) 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 SDK 5 para AWS CloudHSM clientes](client-sdk-5-benefits.md). 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 SDK de AWS CloudHSM cliente 3 al SDK de cliente 5](client-sdk-migration.md). **Topics** + [Preparación teniendo en cuenta los cambios más importantes](#jce-migration-preparation-sdk5) + [Migración a Client SDK 5](#w2aac25c19c21c15) + [Temas relacionados](#java-lib-migrate_to_sdk5-seealso) ## 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.](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/AESGCMEncryptDecryptRunner.java#L43-L50) | ### 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 [1](#explicit_login_sdk3_note). | 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[2](#explicit_login_sdk5_note). | 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](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java#L109C5-L141). | | 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](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java#L143-L202). | + [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](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java#L109C5-L141) en el repositorio AWS CloudHSM GitHub de ejemplos. ### 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](#key_generation_sdk3_note). | 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](#key_generation_sdk5_note). | Para ver un ejemplo de cómo `KeyAttributesMap` generar una clave simétrica, consulte el ejemplo en el repositorio de [SymmetricKeys ejemplos](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/SymmetricKeys.java) 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](#key_pair_generation_sdk3_note). | 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](#key_pair_generation_sdk5_note). | 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](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/AsymmetricKeys.java). 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(); ``` ### 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` y`CloudHSM`. 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 [AWS CloudHSM KeyStore Clase Java para Client SDK 5](alternative-keystore_5.md) 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 `getEntry``getKey`, 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 [Establecimiento de los atributos de las claves con la CLI de CloudHSM](cloudhsm_cli-key-set-attribute.md) de la CLI de CloudHSM. Como alternativa, utilice `KeyStoreWithAttributes#getKeys` 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.](bp-application-integration.md#bp-manage-application). 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 usa la `KeyStoreWithAttributes` clase para buscar una clave y en él se AWS CloudHSM GitHub muestra](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java#L205-L223) un fragmento de código. [1](#using_keystore_att_note) | | 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](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java#L229-L234). Se muestra un fragmento de código de muestra para cada SDK en [2](#delete_key_note). | + [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(); ``` ### 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); ``` ### 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. 1. Desinstale el proveedor de JCE para Client SDK 3. ------ #### [ Amazon Linux 2 ] ``` $ sudo yum remove cloudhsm-client-jce ``` ------ #### [ CentOS 7 ] ``` $ sudo yum remove cloudhsm-client-jce ``` ------ #### [ RHEL 7 ] ``` $ sudo yum remove cloudhsm-client-jce ``` ------ #### [ RHEL 8 ] ``` $ sudo yum remove cloudhsm-client-jce ``` ------ #### [ Ubuntu 16.04 LTS ] ``` $ sudo apt remove cloudhsm-client-jce ``` ------ #### [ Ubuntu 18.04 LTS ] ``` $ sudo apt remove cloudhsm-client-jce ``` ------ 1. Detenga el daemon de cliente para Client SDK 3. ------ #### [ Amazon Linux 2 ] ``` $ sudo service cloudhsm-client stop ``` ------ #### [ CentOS 7 ] ``` $ sudo service cloudhsm-client stop ``` ------ #### [ RHEL 7 ] ``` $ sudo service cloudhsm-client stop ``` ------ #### [ RHEL 8 ] ``` $ sudo service cloudhsm-client stop ``` ------ #### [ Ubuntu 16.04 LTS ] ``` $ sudo systemctl stop cloudhsm-client ``` ------ #### [ Ubuntu 18.04 LTS ] ``` $ sudo systemctl stop cloudhsm-client ``` ------ 1. 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 ``` ------ #### [ Ubuntu 16.04 LTS ] ``` $ sudo apt remove cloudhsm-client ``` ------ #### [ Ubuntu 18.04 LTS ] ``` $ sudo apt remove cloudhsm-client ``` ------ **nota** Es necesario volver a habilitar las configuraciones personalizadas. 1. 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](java-library-install_5.md). 1. 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](cluster-connect.md#connect-how-to). 1. 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 + [Mejores prácticas para AWS CloudHSM](best-practices.md)