Guía de integración de Yubico YubiKey (PIV)
Resumen
Esta guía configura una Yubico YubiKey (PIV / PKCS#11) como fuente de activos criptográficos para el sensor CBOM Secure Discover_HSM en modo PKCS#11. El sensor se conecta en modo de solo lectura y descubre el material almacenado en las ranuras PIV:
- Certificados X.509 en ranuras PIV (autenticación, firma digital, gestión de claves, autenticación de tarjetas)
- Claves públicas RSA y EC asociadas a claves privadas en el dispositivo.
- Metadatos de ranura PIV: identificadores de ranura, algoritmo de clave, tamaño de clave y sujeto/emisor/validez del certificado.
Ranuras PIV cubiertas: 9a (Autenticación), 9c (Firma digital), 9d (Gestión de claves), 9e (Autenticación de tarjeta) y 82-95 (gestión de claves obsoleta). El sensor nunca lee material de clave privada; tanto YKCS11 como ykman solo muestran objetos públicos sin PIN al listar los certificados.
Requisitos previos
- Una llave YubiKey serie 5 (o posterior) con la aplicación PIV habilitada, conectada al host del sensor (o mediante paso de USB).
- Sistema operativo anfitrión Linux (x86_64) o macOS; Python 3.8 o superior.
- opensc instalado (proporciona la herramienta pkcs11).
- La biblioteca Yubico YKCS11 presente (Linux: /usr/lib/x86_64-linux-gnu/libykcs11.so; macOS: /usr/local/lib/libykcs11.dylib).
- La cuenta del sistema operativo del sensor tiene acceso de lectura al dispositivo USB HID/CCID (Linux: grupo plugdev o una regla udev).
- Al menos una ranura PIV contiene un certificado.
Guía paso por paso
Paso 1: Instale YubiKey Manager (ykman) y confirme el dispositivo.
python3 -m venv /opt/cbom/venv && source /opt/cbom/venv/bin/activate pip install yubikey-manager && ykman --version ykman list # expect: YubiKey 5 ... Serial: 12345678 sudo systemctl enable --now pcscd # if no device is listened (Linux) ykman info # confirm: PIV Enabled
Paso 2: Enumerar las ranuras PIV e inspeccionar un certificado.
ykman piv info # lista ranuras pobladas, algoritmo, sujeto, validez ykman piv certificates export 9a /tmp/yubikey_9a_cert.pem openssl x509 -in /tmp/yubikey_9a_cert.pem -text -noout && rm /tmp/yubikey_9a_cert.pem
En la salida de detección solo aparecen las ranuras que contienen certificados; observe qué ranuras están ocupadas.
Paso 3: Verificar el acceso a la biblioteca PKCS#11
pkcs11-tool --module /usr/lib/x86_64-linux-gnu/libykcs11.so --list-objects # macOS: --module /usr/local/lib/libykcs11.dylib ls -la /usr/lib/x86_64-linux-gnu/libykcs11.so # registra la ruta confirmada
Paso 4: Configurar el sensor de seguridad CBOM
sensores: - nombre: Discover_HSM habilitado: verdadero modo: pkcs11 descripción: "Sensor de token de identidad YubiKey PIV / PKCS#11" objetivos: - id: yubikey-primary etiqueta: "YubiKey 5 NFC - Serial 12345678" proveedor: Yubico tipo_de_dispositivo: tarjeta_inteligente serial: "12345678" pkcs11: biblioteca: /usr/lib/x86_64-linux-gnu/libykcs11.so índice_de_ranura: 0 pin_requerido: falso # listar certificados/claves públicas no necesita PIN piv_slots: - { ranura: "9a", etiqueta: Autenticación, habilitado: verdadero } - { ranura: "9c", etiqueta: Firma digital, habilitado: verdadero } - { ranura: "9d", etiqueta: Gestión de claves, habilitado: verdadero } - { ranura: "9e", etiqueta: Autenticación de tarjeta, habilitado: verdadero } descubrimiento: include_certificates: true include_public_keys: true include_private_key_metadata: false # las claves privadas no se pueden exportar schedule: interval_minutes: 60
Paso 5: Validar
sudo systemctl restart cbom-sensor sudo journalctl -u cbom-sensor -f # buscar 'Discovery complete. N object(s) recorded' cbom-sensor run --sensor Discover_HSM --target yubikey-primary --dry-run
Confirme que la lista de resultados muestre al menos un certificado con sujeto, emisor, número de serie y fecha de caducidad completos, y que los activos aparezcan en el inventario bajo Discover_HSM.
Errores comunes
No se puede abrir la biblioteca libykcs11.so
Causa: La biblioteca YKCS11 no está instalada o la ruta configurada es incorrecta.
Solución: Instale libykcs11 (Linux) o yubico-piv-tool (macOS), localícelo con find /usr /lib /opt -name 'libykcs11*', actualice la ruta de la biblioteca y reinicie.
No hay token presente / dispositivo no detectado
Causa: La YubiKey no está insertada, el CCID está desactivado o pcscd no se está ejecutando.
Solución: Confirme la lista de ykman, inicie pcscd, habilite CCID (ykman config usb –enable CCID) y agregue la cuenta del sensor a plugdev.
El espacio está vacío; no se ha detectado ningún certificado.
Causa: Las ranuras PIV configuradas no contienen certificados (recién aprovisionados o borrados).
Resolución: Ejecute ykman piv info para ver las ranuras ocupadas y limite piv_slots a esas; proporcione certificados con ykman piv certificates import si es necesario.
Recomendaciones de seguridad
- Restrinja el acceso físico a los dispositivos YubiKey y al host del sensor.
- Ejecute el sensor como una cuenta dedicada con privilegios bajos (solo plugdev), nunca como root.
- No configure un PIN PIV; la enumeración de certificados/claves públicas no lo requiere; guarde cualquier PIN en un gestor de secretos si alguna vez lo necesita.
- Revise los contadores de reintentos del PIN PIV (ykman piv info) para detectar decrementos inesperados.
- Alerta sobre los certificados en las ranuras 9a-9e que vencen en los próximos 90 días para fomentar su renovación oportuna.
Conclusión
Con ykman confirmando la disponibilidad del dispositivo y la biblioteca YKCS11 PKCS#11 integrada en Discover_HSM, el sensor enumera los certificados X.509 y las claves públicas en las ranuras PIV de YubiKey en modo de solo lectura (sin PIN ni material de clave privada), manteniendo las YubiKeys gestionadas en el inventario CBOM Secure para el seguimiento del ciclo de vida y el cumplimiento normativo.