Guía de integración de Securosys

Requisitos previos

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

1. Proveedor PKCS#11 de Securosys

Se requiere el proveedor PKCS#11 de Securosys (PrimusAPI PKCS#11) para interactuar con el HSM Primus. Esta biblioteca permite la comunicación entre sus aplicaciones y el HSM mediante el estándar PKCS#11.

Pasos de la instalación:

  1. Obtenga el enlace de descarga

    Acceda al Portal de soporte de Securosys para recuperar el PrimusAPI_PKCS11-Enlace de descarga-v#.txt Archivo que contiene las credenciales de descarga y los detalles de la versión. Necesitará una cuenta en el Portal de Soporte de Securosys. Si no la tiene, contacte con el soporte de Securosys para acceder.

  2. Descargar el proveedor

    • Use el comando curl para descargar el paquete del proveedor. Abra el símbolo del sistema y ejecute los siguientes comandos: 

      establecer USUARIO=support.reader.p11
      establecer CRED=

      Reemplazar con el valor del archivo de texto. 

      establecer VERSIÓN=v2.3.4
      curl -L -o "PrimusAPI_PKCS11-%VERSION%.zip" https://%USER%:%CRED%@securosys.jfrog.io/artifactory/p11/PrimusAPI_PKCS11-%VERSION%.zip

    • Alternativamente, puede descargar el archivo ZIP directamente desde Securosys JFrog Artifactory usando un navegador aquí

      • Nombre de usuario: support.reader.p11
      • Contraseña: toma el valor del archivo PrimusAPI_PKCS11-DownloadLink-v#.txt.
  3. Instalar el proveedor
    • Extraiga el archivo ZIP descargado y ubique el instalador MSI (por ejemplo, PrimusAPI_PKCS11--win64.msi) en la carpeta extraída.
    • Haga doble clic en el archivo MSI para ejecutar el instalador y siga las instrucciones para instalar, asegurándose de instalar en la ubicación predeterminada (C:\Program Files\Securosys\Primus P11) a menos que se solicite lo contrario.

      • Nota: Realice una copia de seguridad de los archivos de configuración primus.cfg y .secrets.cfg existentes en el directorio de instalación, ya que el instalador puede sobrescribirlos.

  4. Configurar variable de entorno

    Agregue la ubicación del directorio de los archivos instalados a la RUTA del sistema para un acceso más fácil. 

    C:\Archivos de programa\Securosys\Primus P11
  5. Verificación

    Abra un nuevo símbolo del sistema y ejecute el siguiente comando para probar las herramientas instaladas: 

    ppin-v

2. OpenSSL 3.x

Se requiere OpenSSL 3.x para operaciones criptográficas y para aprovechar el proveedor PKCS#11 con Securosys HSM.

Pasos de la instalación:

  1. Descargar OpenSSL

    Descargue el último instalador de OpenSSL 3.x de 64 bits para Windows usando este este enlace.

  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.
  3. Configurar variable de entorno

    Agregue el directorio binario OpenSSL a la RUTA del sistema:

    C:\Archivos de programa\OpenSSL-Win64\bin
  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

3. Herramienta OpenSC PKCS11

La herramienta PKCS#11 de OpenSC proporciona utilidades como pkcs11-tool para administrar claves y realizar operaciones en el HSM a través de la interfaz PKCS#11.

Pasos de la instalación:

  1. Descargar OpenSC

    Descargue el último instalador de OpenSC para Windows desde la página de lanzamientos de OpenSC en GitHub aquí.

  2. Instalar OpenSC

    Ejecute el instalador MSI como administrador en la ubicación predeterminada (C:\Archivos de programa\Proyecto OpenSC\OpenSC).

  3. Configurar variable de entorno

    Agregue el directorio de herramientas OpenSC a la RUTA del sistema:

    C:\Archivos de programa\Proyecto OpenSC\OpenSC\tools\
  4. Verificación

    Abra un nuevo símbolo del sistema y ejecute el siguiente comando para probar pkcs11-tool 

    herramienta pkcs11 --versión

4. 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:

  1. Descargar herramientas de compilación de Visual Studio

    Descargue Microsoft Build Tools para Visual Studio 2022 usando esto este enlace.

  2. Instalar herramientas de compilación

    Ejecute el instalador (vs_buildtools.exe) con privilegios administrativos.

  3. Verificar instalación

    Abra el “Símbolo del sistema de herramientas nativas x64” desde el menú Inicio y ejecute 

    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

5. Biblioteca de envoltorios PKCS#11 de OpenSC

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:

  1. Descargar 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.
  2. Compilar la biblioteca
    • Abra el “Símbolo del sistema de herramientas nativas x64”.
    • Navegue hasta el directorio libp11
      • cd “C:\Usuarios\\fuente\repositorios\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.

  3. Verificar compilación

    Busque el archivo pkcs11.dll en la carpeta libp11\src. Este es el complemento del motor PKCS#11 de OpenSC.

  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 el proveedor Securosys PKCS#11, OpenSSL y la biblioteca OpenSC PKCS#11 Wrapper para habilitar la comunicación con su HSM Securosys Primus.

1. Configurar el proveedor PKCS#11 de Securosys

El proveedor Securosys PKCS#11 requiere archivos de configuración (primus.cfg y .secrets.cfg) para especificar los detalles de conexión del HSM, como la dirección IP, el puerto, los secretos y la configuración de registro.

Pasos:

  1. Localice el archivo de configuración (primus.cfg)

    Navegue hasta el directorio de instalación del proveedor Securosys PKCS#11, normalmente: 

    C:\Archivos de programa\Securosys\Primus P11
  2. Editar la SECCIÓN DE CONFIGURACIÓN DEL HSM con Detalles del HSM
    • Abra primus.cfg en un editor de texto con privilegios administrativos.
    • Agregue o actualice la siguiente configuración dentro de la “SECCIÓN DE CONFIGURACIÓN DE HSM”, reemplazando los marcadores de posición con los detalles de su HSM: 
      • hsm0 : { host = "NOMBRE DE HOST HSM (como a-api.cloudshsm.com)"; puerto = "PUERTO HSM (como 2310)"; ranuras: { ranura0: { id_cliente = "ID_cliente1 (como Cliente_0)"; nombre_usuario = "NOMBRE_PARTICIÓN1"; usuario_proxy = "USUARIO_SERVICIO"; /* o eliminar si no se necesita proxy */ id = 1; }; /* fin ranura0 */ ranura1: { id_cliente = "ID_cliente2"; nombre_usuario = "NOMBRE_PARTICIÓN2"; usuario_proxy = "USUARIO_SERVICIO"; /* o eliminar si no se necesita proxy */ id = 2; }; /* fin ranura1 */ }; /* fin ranuras */ }; /* fin hsm0 */
  3. Editar la SECCIÓN DE CONFIGURACIÓN DEL REGISTRO con los detalles del registro

    Agregue o actualice la siguiente configuración dentro de la “SECCIÓN DE CONFIGURACIÓN DEL REGISTRO”, reemplazando los marcadores de posición con sus detalles de registro: 

    log : { file = "C:\Archivos de programa\Securosys\Primus P11\primus.log"; /* opcional para Windows */ trace_linenumber = false; trace_timestamp = true; trace_function = true; trace_inout = false; trace_pid = true; trace_filename = false; trace_mask = 0x01; trace_level = 6; /* detalles de nivel de registro 0-7 */ }; /* fin de registro */
  4. Configuración del secreto permanente en el archivo .secrets.cfg
    • Abra un símbolo del sistema y navegue hasta el directorio Primus P11 (si no está configurado en la ruta de la variable de entorno) usando el siguiente comando: 
      • cd C:\Archivos de programa\Securosys\Primus P11
    • Reemplace el valor del marcador de posición con el valor de nombre de usuario HSM que haya configurado en el archivo primus.cfg y ejecute el siguiente comando: 
      • ppin -a -e

      Configure el PKCS11_PIN para el HSM_USERNAME mencionado

      NOTA: Asegúrese de tener permisos de lectura y escritura para modificar el archivo .secrets.cfg con un secreto permanente.

  5. Verificar la conexión con HSM
    • Abra un símbolo del sistema y navegue hasta el directorio Primus P11 (si no está configurado en la ruta de la variable de entorno) usando el siguiente comando: 
      • cd C:\Archivos de programa\Securosys\Primus P11
    • Ejecute la herramienta ppin para probar la conexión HSM:
      • ppin-t

2. Configurar OpenSSL para utilizar el motor PKCS#11

OpenSSL debe configurarse para cargar el proveedor Securosys PKCS#11 (primusP11.dll) y el complemento del motor OpenSC PKCS#11 (pkcs11.dll) para realizar operaciones criptográficas con el HSM.

Pasos:

  1. Localice el archivo de configuración de OpenSSL (openssl.cfg)

    Encuentre el archivo de configuración de OpenSSL:

    C:\Archivos de programa\Archivos comunes\SSL
  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\\Securosys\\Primus P11\\primusP11.dll" PIN = "PKCS11_PIN" init = 0

      Ruta dinámica: Ruta al complemento del motor OpenSC PKCS#11 (pkcs11.dll) compilado en los requisitos previos.

      RUTA DEL MÓDULO: Ruta a la DLL del proveedor PKCS#11 de Securosys.

      PIN: Valor PKCS11_PIN para el nombre de usuario/partición HSM requeridos durante los pasos de secreto permanente.

  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 ]

3. Pruebe la interfaz PKCS#11 con pkcs11-tool

Utilice la herramienta pkcs11 de OpenSC para verificar que la interfaz PKCS#11 pueda comunicarse con el HSM.

Pasos:

  1. Ejecutar pkcs11-tool
    • Abra un símbolo del sistema y navegue hasta el directorio de herramientas de OpenSC, si no está configurado en la ruta de la variable de entorno: 
      • cd “C:\Archivos de programa\Proyecto OpenSC\OpenSC\tools”
    • Ejecute el siguiente comando para enumerar las ranuras disponibles en el HSM: 
      • pkcs11-tool --module "C:\Archivos de programa\Securosys\Primus P11\primusP11.dll" --list-slots

4. Configurar CodeSign Secure

CodeSign Secure requiere configuración para conectarse al HSM Securosys Primus y realizar operaciones de firma de código segura. El archivo app-config.properties especifica los detalles necesarios para una conexión correcta al HSM Securosys Primus.

Pasos:

  1. Localice el archivo app-config.properties

    Navegue a la carpeta CertificateManagement dentro del directorio de instalación de CodeSign Secure y localice el archivo app-config.properties, normalmente: 

    C:\CodeSignSecure\src\CertificateManagement
  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 DE HSM SECUROSYS= 
PIN_HSM_SECUROSYS= 
Seguridad del token HSM 
SECUROSYS DE RANURA HSM=
    • Guarde el archivo con los detalles modificados.