Guía de integración de SmartCard-HSM (Ultrasafe)

Resumen

Esta guía integra un dispositivo SmartCard-HSM (Ultrasafe) con CBOM Secure. El sensor HSM se conecta a través de la interfaz OpenSC PKCS#11 y realiza un descubrimiento de solo lectura de claves asimétricas y simétricas, certificados X.509, objetos de datos y atributos de clave (algoritmo, longitud, etiqueta, CKA_ID, indicadores de uso, estado del ciclo de vida). Utiliza el rol de Usuario Criptográfico y nunca escribe en el dispositivo.

Requisitos previos

  • Dispositivo SmartCard-HSM conectado y reconocido (lector USB o ranura integrada).
  • OpenSC está instalado (opensc, opensc-pkcs11, libpcsclite-dev, pcscd) y pcscd está en ejecución.
  • El dispositivo visible para opensc-tool –list-readers.
  • El PIN del Oficial de Seguridad (OS) (para la inicialización/creación de un PIN de Usuario de Criptografía).
  • Las herramientas sc-hsm-tool y pkcs11-tool están disponibles; el agente del sensor CBOM está instalado en el host.

Guía paso por paso

Paso 1: (Primera vez) Inicializar el dispositivo

Omitir si el dispositivo ya está inicializado con un sistema operativo activo y PIN de usuario. De lo contrario:

sc-hsm-tool --initialize \ --so-pin --alfiler --label "CBOM-HSM" # opcionalmente agregue --dkek-shares 1 para la capacidad de copia de seguridad de claves

Paso 2: Establezca un PIN de usuario criptográfico de solo lectura.

pkcs11-tool \ --module /usr/lib/x86_64-linux-gnu/pkcs11/opensc-pkcs11.so \ --change-pin --login --pin --nuevo-pin

Confirme que el usuario de criptografía puede enumerar objetos:

pkcs11-tool \ --module /usr/lib/x86_64-linux-gnu/pkcs11/opensc-pkcs11.so \ --slot 0 --login --pin --listar-objetos

Paso 3: Identificar la ranura y la biblioteca, otorgar acceso a PC/SC

pkcs11-tool --module /usr/lib/x86_64-linux-gnu/pkcs11/opensc-pkcs11.so --list-slots # anote el índice de ranura y el número de serie del token (por ejemplo, UTSC00000001) sudo usermod -aG plugdev cbom-agent sudo -u cbom-agent pkcs11-tool \ --module /usr/lib/x86_64-linux-gnu/pkcs11/opensc-pkcs11.so --list-slots

Nota: En RHEL/CentOS, la biblioteca se encuentra en /usr/lib64/pkcs11/opensc-pkcs11.so.

Paso 4: Configurar el sensor de seguridad CBOM

sensores: - nombre: Discover_HSM tipo: hsm habilitado: verdadero conexión: pkcs11_module: /usr/lib/x86_64-linux-gnu/pkcs11/opensc-pkcs11.so ranura: 0 token_label: CBOM-HSM token_serial: UTSC00000001 aut: user_type: CKU_USER pin_env: CBOM_HSM_USER_PIN descubrimiento: object_types: [private_keys, public_keys, symmetric_keys, certificates, data_objects] collect_attributes: [CKA_LABEL, CKA_ID, CKA_CLASS, CKA_KEY_TYPE, CKA_VALUE_LEN, CKA_MODULUS_BITS, CKA_EC_PARAMS, CKA_SIGN, CKA_VERIFY, CKA_EXTRACTABLE, CKA_SENSITIVE, CKA_START_DATE, CKA_END_DATE] programación: intervalo: 24h salida: etiquetas: { tipo_de_dispositivo: smartcard-hsm, proveedor: ultrasafe } exportar CBOM_HSM_USER_PIN=" " sudo -E systemctl reiniciar cbom-agent

Paso 5: Validar

cbom-agent sensor run --name Discover_HSM --dry-run

Confirme que el módulo se carga, el token se conecta, CKU_USER se autentica y se descubren las claves/certificados; verifique en Activos → Claves criptográficas filtradas por Origen: Discover_HSM.

Errores comunes

PIN_CKR_INCORRECT

Causa: La variable PIN no coincide con el PIN del usuario de criptografía o no se exporta al entorno del agente.

Resolución: Vuelva a exportar CBOM_HSM_USER_PIN y reinicie con systemctl restart cbom-agent; verifique que esté configurado en el entorno del agente.

Error de PCSC: No existe tal dispositivo

Causa: pcscd no se está ejecutando, el lector está desconectado o el agente no tiene acceso al lector.

Solución: Reinicie pcscd, confirme con opensc-tool –list-readers y asegúrese de que cbom-agent esté en el grupo plugdev.

ID DE RANURA CKR_NO VÁLIDO

Causa: El índice de la ranura cambió después de una reenumeración USB.

Solución: Vuelva a ejecutar –list-slots, o utilice token_label / token_serial para una identificación estable.

Recomendaciones de seguridad

  • Utilice únicamente el PIN de usuario de Crypto, nunca el PIN de SO, ya que este puede modificar la configuración del dispositivo.
  • Almacene el PIN en un gestor de secretos en lugar de en un perfil de shell o un archivo de unidad.
  • Restringir la configuración a la cuenta del agente (chmod 600).
  • Habilite el bloqueo por PIN (5 intentos o menos) y mantenga cualquier recurso compartido DKEK sin conexión.
  • Limite la membresía de plugdev y revise los registros de descubrimiento de CBOM para detectar fallos de autenticación.

Conclusión

El sensor HSM se conecta al SmartCard-HSM mediante OpenSC PKCS#11, se autentica como un usuario criptográfico de solo lectura y enumera todos los objetos clave, certificados y objetos de datos, proporcionando un inventario criptográfico actualizado continuamente en CBOM Secure.