Yubico YubiKey (PIV) integrationsguide

Översikt

Den här guiden konfigurerar en Yubico YubiKey (PIV / PKCS#11) som en kryptografisk tillgångskälla för CBOM Secure Discover_HSM-sensorn i PKCS#11-läge. Sensorn ansluter skrivskyddat och upptäcker material som lagras i PIV-platser:

  • X.509-certifikat i PIV-platser (autentisering, digital signatur, nyckelhantering, kortautentisering)
  • RSA- och EC-nycklar associerade med privata nycklar pÃ¥ enheten
  • PIV-platsmetadata: plats-ID:n, nyckelalgoritm, nyckelstorlek och certifikatämne/utfärdare/giltighet

Täckta PIV-platser: 9a (Autentisering), 9c (Digital signatur), 9d (Nyckelhantering), 9e (Kortautentisering) och 82-95 (pensionerad nyckelhantering). Sensorn läser aldrig privat nyckelmaterial – både YKCS11 och ykman exponerar endast offentliga objekt utan PIN-kod vid lista av certifikat.

Förutsättningar

  1. En YubiKey 5-serie (eller senare) med PIV-appleten aktiverad, ansluten till sensorvärden (eller via USB-genomströmning).
  2. Linux (x86_64) eller macOS-värd; Python 3.8+.
  3. opensc installerat (tillhandahåller pkcs11-verktyget).
  4. Yubico YKCS11-biblioteket finns (Linux: /usr/lib/x86_64-linux-gnu/libykcs11.so; macOS: /usr/local/lib/libykcs11.dylib).
  5. Sensorns operativsystemkonto har läsåtkomst till USB HID/CCID-enheten (Linux: plugdev-grupp eller en udev-regel).
  6. Minst en PIV-plats innehåller ett certifikat.

Steg-för-steg-guide

Steg 1: Installera YubiKey Manager (ykman) och bekräfta enheten 

python3 -m venv /opt/cbom/venv && source /opt/cbom/venv/bin/activate pip install yubikey-manager && ykman --version ykman list # förvänta dig: YubiKey 5 ... Serienummer: 12345678 sudo systemctl enable --now pcscd # om ingen enhet listas (Linux) ykman info # bekräfta: PIV aktiverad

Steg 2: Räkna upp PIV-platser och inspektera ett certifikat

ykman piv info # listar ifyllda platser, algoritm, ämne, giltighet ykman piv certifikat export 9a /tmp/yubikey_9a_cert.pem openssl x509 -in /tmp/yubikey_9a_cert.pem -text -noout && rm /tmp/yubikey_9a_cert.pem

Endast platser som innehåller certifikat visas i identifieringsutdata – notera vilka platser som är ifyllda.

Steg 3: Verifiera PKCS#11-biblioteksåtkomst

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 # registrera den bekräftade sökvägen

Steg 4: Konfigurera CBOM Secure Sensor

sensorer: - namn: Discover_HSM enabled: true läge: pkcs11 beskrivning: "YubiKey PIV / PKCS#11 identitetstokensensor" mål: - id: yubikey-primary etikett: "YubiKey 5 NFC - Serienummer 12345678" leverantör: Yubico device_type: smart_card serienummer: "12345678" pkcs11: bibliotek: /usr/lib/x86_64-linux-gnu/libykcs11.so slot_index: 0 pin_required: false # lista över certifikat/publika nycklar behöver ingen PIN-kod piv_slots: - { slot: "9a", etikett: Autentisering, enabled: true } - { slot: "9c", etikett: Digital signatur, enabled: true } - { slot: "9d", etikett: Nyckelhantering, enabled: true } - { slot: "9e", etikett: Kortautentisering, enabled: true } discovery: include_certificates: true include_public_keys: true include_private_key_metadata: false # privata nycklar kan inte exporteras schedule: interval_minutes: 60

Steg 5: Validera 

sudo systemctl restart cbom-sensor sudo journalctl -u cbom-sensor -f # leta efter 'Upptäckt klar. N objekt registrerade' cbom-sensor run --sensor Discover_HSM --target yubikey-primary --dry-run

Bekräfta att utdata listar minst ett certifikat med ämne, utfärdare, serienummer och utgångsdatum ifyllt, och att tillgångar visas i inventeringen under Discover_HSM.

Vanliga fel

Kan inte öppna biblioteket libykcs11.so

Orsak: YKCS11-biblioteket är inte installerat, eller så är den konfigurerade sökvägen felaktig.

Lösning: Installera libykcs11 (Linux) eller yubico-piv-tool (macOS), sök upp med find /usr /lib /opt -name 'libykcs11*', uppdatera bibliotekets sökväg och starta om.

Ingen token finns / enhet upptäcktes inte

Orsak: YubiKey är inte isatt, CCID är inaktiverat eller pcscd körs inte.

Lösning: Bekräfta ykman-listan, starta pcscd, aktivera CCID (ykman config usb –enable CCID) och lägg till sensorkontot i plugdev.

Platsen är tom – inget certifikat hittades

Orsak: De konfigurerade PIV-platserna innehåller inga certifikat (nyligen etablerade eller rensade).

Lösning: Kör ykman piv info för att se ifyllda platser och begränsa piv_slots till dessa; etablera certifikat med ykman piv certificates import om det behövs.

Säkerhetsrekommendationer

  • Begränsa fysisk Ã¥tkomst till YubiKey-enheter och sensorvärden.
  • Kör sensorn som ett dedikerat konto med lÃ¥g behörighet (endast plugdev), roota aldrig.
  • Konfigurera inte en PIV-PIN – certifikat-/publik nyckeluppräkning behöver ingen; lagra vilken PIN-kod som helst i en hemlighetshanterare om det nÃ¥gonsin behövs.
  • Granska PIV PIN-Ã¥terförsöksräknare (ykman piv info) för oväntade minskningar.
  • Aviseringar om certifikat i slot 9a-9e som löper ut inom 90 dagar för att driva pÃ¥ snabb förnyelse.

Slutsats

Med ykman som bekräftar enhetens beredskap och YKCS11 PKCS#11-biblioteket kopplat till Discover_HSM, räknar sensorn upp X.509-certifikat och publika nycklar över YubiKey PIV-platser helt skrivskyddade – ingen PIN-kod, inget privat nyckelmaterial – vilket håller hanterade YubiKeys i CBOM Secure-inventeringen för livscykel- och efterlevnadsspårning.