Guía de integración del conector Utimaco

Requisitos previos

Para que el motor PKCS#11 funcione correctamente con su HSM Utimaco y CodeSign Secure de Encryption Consulting, necesitará algunos elementos clave. Estos son los pasos para instalar los recursos esenciales para configurar el entorno de Windows:

Servidor de seguridad Utimaco
Utimaco SecurityServer proporciona bibliotecas, herramientas e interfaces criptográficas (p. ej., PKCS#11, CSP y JCE) para gestionar claves y realizar operaciones criptográficas de forma segura. El software incluye el SDK de CryptoServer, herramientas administrativas y simuladores, lo que facilita una integración fluida con HSM para una mayor seguridad y cumplimiento normativo.

Pasos de la instalación:
Paso 1: Descargue el proveedor
Descargue el proveedor (por ejemplo, SecurityServerEvaluation-V6.1.1 para Windows) desde el portal de clientes de Utimaco.
Paso 2: Instalar el proveedor
- Extraiga el paquete descargado, ejecute el instalador MSI y siga las instrucciones para configurar el servidor de seguridad Utimaco en su sistema.
- Instalará las herramientas necesarias en la ubicación predeterminada (C:\Archivos de programa\Utimaco), a menos que se especifique lo contrario durante la instalación, y también creará accesos directos para las siguientes herramientas en el escritorio del usuario actual para un acceso más fácil:
  - Administración de CryptoServer
  - Administración del servidor criptográfico PKCS#11
  - Simulador de CryptoServer
- Junto con esto, también modificará las variables de entorno con las ubicaciones seleccionadas y los archivos de configuración de Utimaco SecurityServer.
OpenSSL 3.x
Se requiere OpenSSL 3.x para operaciones criptográficas y para aprovechar el proveedor PKCS#11 con el HSM Utimaco.

Pasos de la instalación:
Paso 1: Descargar OpenSSL
Descargue el último instalador de OpenSSL 3.x de 64 bits para Windows usando este este enlace.
Paso 2: Instalar OpenSSL
- Ejecute el instalador descargado con privilegios administrativos.
- Elija el directorio de instalación predeterminado (C:\Archivos de programa\OpenSSL-Win64) a menos que tenga requisitos específicos.
Paso 3: Configurar la variable de entorno
Agregue el directorio binario OpenSSL a la RUTA del sistema:
- C:\Archivos de programa\OpenSSL-Win64\bin
Paso 4: verificación
Abra un nuevo símbolo del sistema y ejecute el siguiente comando para probar la instalación de openssl.
```
versión openssl
```

Java Runtime Environment

Utimaco SecurityServer también requiere un entorno de ejecución de Java (versión probada: Java 15). Consulte la siguiente matriz para comprobar la versión compatible con Java:

Java Runtime Environment	Versión
Oracle Java	8,11,15
OpenJDK	8,11,15

Pasos de la instalación:

Paso 1: Descargue Java 15

Descargue el ejecutable Java compatible desde aquí para su sistema Windows.

Paso 2: Instalar Java 15

Ejecute el ejecutable descargado y siga las instrucciones para configurar Java 15.

Paso 3: verificación

Abra un nuevo símbolo del sistema y ejecute el siguiente comando para probar la instalación de Java.

java -version

Herramientas de compilación de Microsoft Visual Studio
Se requieren las herramientas de compilación de Microsoft Visual Studio para compilar la biblioteca contenedora OpenSC PKCS#11 (libp11) en Windows

Pasos de la instalación:
Paso 1: Descargue las herramientas de compilación de Visual Studio
Descargue Microsoft Build Tools para Visual Studio 2022 usando esto este enlace.
Paso 2: Instalar herramientas de compilación
Ejecute el instalador (vs_buildtools.exe) con privilegios administrativos.
Paso 3: Verificar la instalación
Abra el panel de Símbolo del sistema de herramientas nativas x64 desde el menú Inicio y ejecutar
```
nmake/?
```
Esto debería mostrar la ayuda de la utilidad nmake, confirmando que las herramientas de compilación están instaladas.
NOTA: El “Símbolo del sistema de x64 Native Tools” debe estar presente dentro de C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Visual Studio 2022\Visual Studio Tools\VC
Biblioteca de envoltorios OpenSC PKCS#11
La biblioteca contenedora OpenSC PKCS#11 (libp11) proporciona el complemento del motor PKCS#11 (pkcs11.dll) para que OpenSSL interactúe con el HSM.

Pasos de la instalación:
Paso 1: Descargue el código fuente
- Clone el repositorio OpenSC/libp11 desde GitHub o descárguelo como un archivo ZIP.
- Clonar usando Git (si está instalado):
```
clon git https://github.com/OpenSC/libp11.git C:\Usuarios\ \fuente\repos\libp11
```
- O descargue el ZIP desde aquí este enlace y extraerlo a C:\Users\ \fuente\repos\libp11.
Paso 2: Compilar la biblioteca
- Abra el “Símbolo del sistema de herramientas nativas x64”.
- Vaya al directorio libp11, es decir, cd “C:\Users\ \fuente\repos\libp11”
- Ejecute el comando nmake para compilar la biblioteca
```
nmake /f Makefile.mak OPENSSL_DIR="C:\Archivos de programa\OpenSSL-Win64" COMPILACIÓN_PARA=WIN64
```
  NOTA: Asegúrese de que OPENSSL_DIR apunte a su directorio de instalación de OpenSSL.
Paso 3: Verificar la compilación
Busque el archivo pkcs11.dll en la carpeta libp11\src. Este es el complemento del motor PKCS#11 de OpenSC.
Paso 4: Copiar la carpeta SRC
Copie la carpeta src que acaba de crear en su directorio bin de OpenSSL, es decir, C:\Program Files\OpenSSL-Win64\bin

Configuration

Después de instalar los requisitos previos, debe configurar Utimaco SecuritySever, OpenSSL y la biblioteca OpenSC PKCS#11 Wrapper para habilitar la comunicación con su Utimaco HSM.

Configurar el servidor de seguridad de Utimaco
Para configurar Utimaco SecurityServer es necesario configurar variables de entorno y actualizar archivos de configuración (por ejemplo, configuración PKCS#11) para administrar el acceso y las operaciones del HSM de forma segura.

Pasos:
Paso 1: Localice el archivo de configuración (cs_pkcs11_R3.cfg)
Navegue al directorio de instalación del proveedor PKCS#11 de Utimaco, normalmente: C:\ProgramData\Utimaco\PKCS11_R3
Paso 2: Actualice la dirección IP del HSM
En la sección [HSMCluster], actualice la dirección IP de su HSM Utimaco. Recuerde descomentar (eliminar el símbolo de almohadilla) la línea (p. ej., [email protected]) donde has añadido la IP.

Aquí, utilizaremos un simulador local que se ejecuta, de forma predeterminada, en el puerto 3001 del host local (127.0.0.1).
Crear roles de usuario para un espacio
Para generar claves y certificados utilizando Utimaco SecurityServer, deberá crear y definir roles de usuario: administrador, oficial de seguridad (SO) y usuario criptográfico.

Pasos:
Paso 1: Iniciar el simulador de CryptoServer
- Inicie el Simulador de CryptoServer, provisto en el escritorio, para inicializar las configuraciones requeridas.
  
  NOTA: En caso de que utilice un HSM Utimaco real, deberá iniciar la aplicación CryptoServer Administrator, también presente en el escritorio.
Paso 2: Localice la aplicación de administración de CryptoServer PKCS#11
Abra la aplicación PKCS#11 CryptoServer, que normalmente se encuentra en el escritorio del usuario

Paso 3: Seleccione la ranura requerida
En la tabla de la izquierda, haga clic en el número de ranura deseado. Aquí, hemos seleccionado la ranura número 1.

Paso 4: Inicie sesión como ADMIN
- Vaya a la sección Iniciar sesión/Cerrar sesión desde la barra superior y seleccione la opción “Iniciar sesión genérico”.
- Ingrese “ADMIN” como nombre de usuario y seleccione la opción “Keyfile” para la contraseña.
- Examine el archivo de claves e introduzca el archivo de contraseñas. Al ejecutar el simulador, seleccione el archivo "ADMIN_SIM.key"; de lo contrario, utilice "ADMIN_EC.key". Estos archivos de claves suelen encontrarse en el directorio "C:\Archivos de programa\Utimaco\SecurityServer\Administration".
- Haga clic en Iniciar sesión para iniciar sesión como usuario ADMIN. Aparecerá un candado en el estado de inicio de sesión de esa ranura en la tabla izquierda.
Paso 5: Inicializar el token para esta ranura
- Abra la sección Gestión de Slots desde la barra superior y seleccione la opción “Init Token”.
- Ingrese el nombre de token requerido para esta ranura y proporcione un PIN temporal para el rol de Oficial de seguridad (este PIN se cambiará en los pasos posteriores)
- Haga clic en el botón "Iniciar token" para finalizar el token. Se desactivará la opción "Iniciar token" para esta ranura y se activará la opción "Eliminar SO".
- Ahora, vaya a la sección Iniciar sesión/Cerrar sesión y haga clic en la opción “Cerrar sesión todo” para cerrar la sesión de todos los roles de usuario activos.
- Se mostrará una marca de verificación verde en la tabla de la izquierda debajo de Token Init para esta ranura.
Paso 6: Configurar el rol de Oficial de Seguridad
- Vaya a la sección “Iniciar sesión/Cerrar sesión” y seleccione la opción “Iniciar sesión SO”.
- Ingrese el PIN temporal de SO que configuró en el paso anterior para el rol de Oficial de Seguridad y haga clic en el botón "Iniciar sesión". Aparecerá un símbolo de candado en la tabla izquierda, debajo de "Estado de inicio de sesión".
- Ahora, vaya a la sección Administración de ranuras desde la barra superior y configure un nuevo PIN para el rol de Oficial de seguridad seleccionando la opción “Establecer PIN”.
- Establezca un nuevo PIN SO para el oficial de seguridad de esta ranura.
- Cerrará su sesión actual como SO, lo cual puede ver en la sección “Iniciar sesión/Cerrar sesión” o en la columna “Estado de inicio de sesión” de la tabla del lado izquierdo.
- Inicie sesión nuevamente como SO con el nuevo PIN de SO seleccionando “Iniciar sesión SO” en la sección “Iniciar sesión/Cerrar sesión”.
- Le mostrará un candado en la tabla del lado izquierdo después de iniciar sesión correctamente.
Paso 7: Configurar el rol de usuario criptográfico
- Vaya a la sección “Administración de ranuras” y seleccione la opción “PIN de inicialización”.
- Ingrese un PIN temporal para el usuario criptográfico para esta ranura y haga clic en el botón “Iniciar PIN”.
- Ahora cierre la sesión de todas las sesiones activas desde la sección “Iniciar sesión/Cerrar sesión”.
- Ahora inicie sesión como Usuario Criptográfico usando el PIN temporal seleccionando la opción “Iniciar sesión Usuario” en la sección “Iniciar sesión/Cerrar sesión”.
- Vaya a la sección “Administración de ranuras” y configure un nuevo PIN para el usuario criptográfico utilizando la opción “Establecer PIN”.
- Actualizar el PIN del usuario criptográfico en esta ranura
- Esto cerrará su sesión actual. Vuelva a iniciar sesión como el usuario desde la sección "Iniciar sesión/Cerrar sesión".
- Ya tiene todos los roles necesarios para esta ranura. Deberá iniciar sesión como usuario criptográfico para gestionar cualquier objeto, como la generación de claves o certificados.
Configurar OpenSSL para utilizar el motor PKCS#11
OpenSSL debe configurarse para cargar el proveedor PKCS#11 de Utimaco (cs_pkcs11_R3.dll) y el complemento del motor PKCS#11 de OpenSC (pkcs11.dll) para realizar operaciones criptográficas con el HSM.

Pasos:
Paso 1: Localice el archivo de configuración de OpenSSL (openssl.cfg)
Busque el archivo de configuración de OpenSSL: C:\Archivos de programa\Archivos comunes\SSL
Paso 2: Editar la configuración de OpenSSL
- Abra openssl.cfg en un editor de texto con privilegios administrativos.
- Agregue lo siguiente en la parte superior del archivo para habilitar la carga dinámica del motor:
```
openssl_conf = openssl_init
```
- Agregue lo siguiente al final del archivo para configurar el motor PKCS#11:
```
                                                    [openssl_init] motores = sección_motor [sección_motor] pkcs11 = sección_pkcs11 [sección_pkcs11] id_motor = pkcs11 ruta_dinámica = C:\\Archivos de programa\\OpenSSL-Win64\\src\\pkcs11.dll RUTA_MÓDULO = C:\\Archivos de programa\\Utimaco\\SecurityServer\\Lib\\cs_pkcs11_R3.dll init = 0

                                                
```
Paso 3: Verificar la configuración y la conexión de OpenSSL
- Abra un símbolo del sistema y ejecute:
```
motor openssl pkcs11 -t
```
- El resultado esperado confirma que el motor PKCS#11 está disponible:
  
  (pkcs11) Motor PKCS#11
  
  [ disponible ]
Configurar CodeSign Secure
CodeSign Secure requiere configuración para conectarse al HSM de Utimaco SecurityServer y realizar operaciones de firma de código seguras. El archivo app-config.properties especifica los detalles necesarios para conectarse correctamente al HSM de Utimaco.

Pasos:
Paso 1: Localice el archivo app-config.properties
Navegue a la carpeta CertificateManagement dentro del directorio de instalación de CodeSign Secure y ubique el archivo app-config.properties, normalmente: C:\CodeSignSecure\src\CertificateManagement
Paso 2: Actualizar los campos de detalles del HSM
- Abra app-config.properties en un editor de texto con privilegios administrativos.
- Actualice los siguientes campos, reemplazando los marcadores de posición con los detalles de su conexión HSM:
  
  RUTA DE LA LIBRO HSM_UTIMACO=
  
  PIN_HSM_UTIMACO=
  
  HSM_TOKEN_UTIMACO=
  
  HSM_SLOT_UTIMACO=
- Guarde el archivo con los detalles modificados.