Integratiehandleiding voor Yubico YubiKey (PIV)

Overzicht

Deze handleiding beschrijft hoe een Yubico YubiKey (PIV / PKCS#11) geconfigureerd kan worden als cryptografische bron voor de CBOM Secure Discover_HSM-sensor in PKCS#11-modus. De sensor maakt verbinding in alleen-lezenmodus en detecteert materiaal dat is opgeslagen in PIV-slots:

  • X.509-certificaten in PIV-slots (authenticatie, digitale handtekening, sleutelbeheer, kaartauthenticatie)
  • RSA- en EC-publieke sleutels die gekoppeld zijn aan privésleutels op het apparaat.
  • PIV-slotmetadata: slot-ID's, sleutelalgoritme, sleutelgrootte en certificaatonderwerp/uitgever/geldigheid

Bedekte PIV-slots: 9a (Authenticatie), 9c (Digitale handtekening), 9d (Sleutelbeheer), 9e (Kaartauthenticatie) en 82-95 (beheer van uitgefaseerde sleutels). De sensor leest nooit privé-sleutelmateriaal – zowel YKCS11 als ykman tonen alleen openbare objecten zonder pincode bij het weergeven van certificaten.

Voorwaarden

  1. Een YubiKey 5-serie (of nieuwer) met de PIV-applet ingeschakeld, aangesloten op de sensorhost (of via USB-doorvoer).
  2. Linux (x86_64) of macOS host; Python 3.8+.
  3. opensc is geïnstalleerd (levert pkcs11-tool).
  4. De Yubico YKCS11-bibliotheek aanwezig (Linux: /usr/lib/x86_64-linux-gnu/libykcs11.so; macOS: /usr/local/lib/libykcs11.dylib).
  5. Het besturingssysteemaccount van de sensor heeft leesrechten voor het USB HID/CCID-apparaat (Linux: plugdev-groep of een udev-regel).
  6. Ten minste één PIV-slot bevat een certificaat.

Stapsgewijze handleiding

Stap 1: Installeer YubiKey Manager (ykman) en bevestig het apparaat. 

python3 -m venv /opt/cbom/venv && source /opt/cbom/venv/bin/activate pip install yubikey-manager && ykman --version ykman list # verwacht: YubiKey 5 ... Serienummer: 12345678 sudo systemctl enable --now pcscd # als er geen apparaat wordt weergegeven (Linux) ykman info # bevestigen: PIV ingeschakeld

Stap 2: PIV-slots opsommen en een certificaat inspecteren

ykman piv info # geeft een overzicht van de gevulde slots, het algoritme, het onderwerp en de geldigheidsduur 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

Alleen slots met certificaten verschijnen in de ontdekkingsuitvoer – let op welke slots gevuld zijn.

Stap 3: Controleer de toegang tot de PKCS#11-bibliotheek

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 # registreer het bevestigde pad

Stap 4: Configureer de CBOM Secure Sensor

Sensoren: - naam: Discover_HSM ingeschakeld: true modus: pkcs11 beschrijving: "YubiKey PIV / PKCS#11 identiteitstokensensor" doelen: - id: yubikey-primary label: "YubiKey 5 NFC - Serienummer 12345678" leverancier: Yubico apparaattype: smartcard serienummer: "12345678" pkcs11: bibliotheek: /usr/lib/x86_64-linux-gnu/libykcs11.so slotindex: 0 pincode vereist: false # Lijst met certificaten/publieke sleutels vereist geen pincode piv_slots: - { slot: "9a", label: Authenticatie, ingeschakeld: true } - { slot: "9c", label: Digitale handtekening, ingeschakeld: true } - { slot: "9d", label: Sleutelbeheer, ingeschakeld: true } - { slot: "9e", label: Kaartauthenticatie, ingeschakeld: true } ontdekking: inclusief certificaten: true include_public_keys: true include_private_key_metadata: false # privésleutels kunnen niet worden geëxporteerd schedule: interval_minutes: 60

Stap 5: Valideren 

sudo systemctl restart cbom-sensor sudo journalctl -u cbom-sensor -f # zoek naar 'Discovery complete. N object(s) recorded' cbom-sensor run --sensor Discover_HSM --target yubikey-primary --dry-run

Controleer of de uitvoerlijst ten minste één certificaat bevat met ingevulde onderwerp-, uitgever-, serie- en vervaldatumgegevens, en of de activa in de inventaris onder Discover_HSM verschijnen.

Veel voorkomende fouten

Kan de bibliotheek libykcs11.so niet openen.

Oorzaak: De YKCS11-bibliotheek is niet geïnstalleerd of het geconfigureerde pad is onjuist.

Oplossing: Installeer libykcs11 (Linux) of yubico-piv-tool (macOS), zoek de bibliotheek op met find /usr /lib /opt -name 'libykcs11*', werk het bibliotheekpad bij en herstart de computer.

Geen token aanwezig / apparaat niet gedetecteerd

Oorzaak: De YubiKey is niet geplaatst, CCID is uitgeschakeld of pcscd is niet actief.

Oplossing: Controleer de ykman-lijst, start pcscd, schakel CCID in (ykman config usb –enable CCID) en voeg het sensoraccount toe aan plugdev.

Slot is leeg – geen certificaat gevonden

Oorzaak: De geconfigureerde PIV-slots bevatten geen certificaten (nieuw aangemaakt of verwijderd).

Oplossing: Voer `ykman piv info` uit om de gevulde slots te bekijken en beperk `piv_slots` tot die slots; maak indien nodig certificaten aan met `ykman piv certificates import`.

Beveiligingsaanbevelingen

  • Beperk de fysieke toegang tot YubiKey-apparaten en de sensorhost.
  • Voer de sensor uit als een speciaal account met lage privileges (alleen plugdev), nooit als root.
  • Configureer geen PIV-PIN; certificaat-/publieke-sleutelopsomming vereist er geen. Bewaar een eventuele PIN in een geheimenbeheerder als deze ooit nodig is.
  • Controleer de PIV PIN-herhalingstellers (ykman piv info) op onverwachte verlagingen.
  • Een waarschuwing voor certificaten in de categorieën 9a-9e die binnen 90 dagen verlopen, om tijdige verlenging te stimuleren.

Conclusie

Nadat ykman de gereedheid van het apparaat heeft bevestigd en de YKCS11 PKCS#11-bibliotheek is gekoppeld aan Discover_HSM, inventariseert de sensor X.509-certificaten en openbare sleutels in alle YubiKey PIV-slots volledig alleen-lezen – zonder pincode of privésleutelmateriaal – waardoor beheerde YubiKeys in de CBOM Secure-inventaris blijven voor het bijhouden van de levenscyclus en naleving.