Yubico YubiKey (PIV) Integrationsleitfaden

Übersicht

Diese Anleitung konfiguriert einen Yubico YubiKey (PIV / PKCS#11) als kryptografische Asset-Quelle für den CBOM Secure Discover_HSM-Sensor im PKCS#11-Modus. Der Sensor verbindet sich schreibgeschützt und erkennt in PIV-Slots gespeicherte Daten.

  • X.509-Zertifikate in PIV-Slots (Authentifizierung, digitale Signatur, Schlüsselverwaltung, Kartenauthentifizierung)
  • RSA- und EC-öffentliche Schlüssel, die mit geräteinternen privaten Schlüsseln verknüpft sind
  • PIV-Slot-Metadaten: Slot-IDs, Schlüsselalgorithmus, Schlüssellänge und Zertifikatsinhaber/Aussteller/Gültigkeit

Abgedeckte PIV-Slots: 9a (Authentifizierung), 9c (Digitale Signatur), 9d (Schlüsselverwaltung), 9e (Kartenauthentifizierung) und 82–95 (ausgemusterte Schlüsselverwaltung). Der Sensor liest niemals private Schlüssel – sowohl YKCS11 als auch ykman geben beim Auflisten von Zertifikaten nur öffentliche Objekte ohne PIN aus.

Voraussetzungen:

  1. Ein YubiKey der 5er-Serie (oder neuer) mit aktiviertem PIV-Applet, der mit dem Sensor-Host (oder über USB-Passthrough) verbunden ist.
  2. Hostsystem: Linux (x86_64) oder macOS; Python 3.8+.
  3. opensc ist installiert (stellt das pkcs11-Tool bereit).
  4. Die Yubico YKCS11-Bibliothek ist vorhanden (Linux: /usr/lib/x86_64-linux-gnu/libykcs11.so; macOS: /usr/local/lib/libykcs11.dylib).
  5. Das Betriebssystemkonto des Sensors hat Lesezugriff auf das USB HID/CCID-Gerät (Linux: Gruppe plugdev oder eine udev-Regel).
  6. Mindestens ein PIV-Steckplatz enthält ein Zertifikat.

Schritt-für-Schritt-Anleitung

Schritt 1: Installieren Sie den YubiKey Manager (ykman) und bestätigen Sie das Gerät. 

python3 -m venv /opt/cbom/venv && source /opt/cbom/venv/bin/activate pip install yubikey-manager && ykman --version ykman list # erwartet: YubiKey 5 ... Seriennummer: 12345678 sudo systemctl enable --now pcscd # falls kein Gerät aufgeführt ist (Linux) ykman info # Bestätigung: PIV aktiviert

Schritt 2: PIV-Slots auflisten und Zertifikat prüfen

ykman piv info # listet belegte Slots, Algorithmus, Subjekt, Gültigkeit auf 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

Nur Slots, die Zertifikate enthalten, werden in der Discovery-Ausgabe angezeigt – beachten Sie, welche Slots belegt sind.

Schritt 3: Überprüfen Sie den PKCS#11-Bibliothekszugriff

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 # Bestätigten Pfad speichern

Schritt 4: Konfigurieren Sie den CBOM-Sicherheitssensor

Sensoren: - Name: Discover_HSM aktiviert: true Modus: pkcs11 Beschreibung: "YubiKey PIV / PKCS#11 Identitätstoken-Sensor" Ziele: - ID: yubikey-primary Bezeichnung: "YubiKey 5 NFC - Seriennummer 12345678" Hersteller: Yubico Gerätetyp: Smartcard Seriennummer: "12345678" pkcs11: Bibliothek: /usr/lib/x86_64-linux-gnu/libykcs11.so Slot-Index: 0 PIN erforderlich: false # Auflistung von Zertifikaten/öffentlichen Schlüsseln erfordert keine PIN piv_slots: - { Slot: "9a", Bezeichnung: Authentifizierung, aktiviert: true } - { Slot: "9c", Bezeichnung: Digitale Signatur, aktiviert: true } - { Slot: "9d", Bezeichnung: Schlüsselverwaltung, aktiviert: true } - { Slot: "9e", Bezeichnung: Kartenauthentifizierung, aktiviert: true } Erkennung: Zertifikate einschließen: true include_public_keys: true include_private_key_metadata: false # Private Schlüssel sind nicht exportierbar schedule: interval_minutes: 60

Schritt 5: Validieren 

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

Prüfen Sie, ob die Ausgabe mindestens ein Zertifikat mit ausgefüllten Feldern für Betreff, Aussteller, Seriennummer und Ablaufdatum enthält und ob Assets im Inventar unter Discover_HSM angezeigt werden.

Häufige Fehler

Die Bibliothek libykcs11.so konnte nicht geöffnet werden.

Ursache: Die YKCS11-Bibliothek ist nicht installiert oder der konfigurierte Pfad ist falsch.

Lösung: Installieren Sie libykcs11 (Linux) oder yubico-piv-tool (macOS), suchen Sie mit find /usr /lib /opt -name 'libykcs11*' nach libykcs11, aktualisieren Sie den Bibliothekspfad und starten Sie den Computer neu.

Kein Token vorhanden / Gerät nicht erkannt

Ursache: Der YubiKey ist nicht eingesteckt, CCID ist deaktiviert oder pcscd wird nicht ausgeführt.

Lösung: Bestätigen Sie die ykman-Liste, starten Sie pcscd, aktivieren Sie CCID (ykman config usb –enable CCID) und fügen Sie das Sensorkonto zu plugdev hinzu.

Slot leer – kein Zertifikat gefunden

Ursache: Die konfigurierten PIV-Slots enthalten keine Zertifikate (weder neu bereitgestellte noch gelöschte).

Lösung: Führen Sie ykman piv info aus, um die belegten Slots anzuzeigen und piv_slots auf diese zu beschränken; stellen Sie gegebenenfalls Zertifikate mit ykman piv certificates import bereit.

Sicherheitsempfehlungen

  • Beschränken Sie den physischen Zugriff auf YubiKey-Geräte und den Sensor-Host.
  • Führen Sie den Sensor als dediziertes Benutzerkonto mit geringen Berechtigungen aus (nur plugdev), niemals als Root-Benutzer.
  • Konfigurieren Sie keine PIV-PIN – die Zertifikats-/Public-Key-Enumeration benötigt keine; speichern Sie eine PIN bei Bedarf in einem Secrets Manager.
  • Überprüfen Sie die PIV-PIN-Wiederholungszähler (ykman piv info) auf unerwartete Dekremente.
  • Hinweis zu Zertifikaten in den Feldern 9a-9e, die innerhalb von 90 Tagen ablaufen, um eine rechtzeitige Verlängerung zu gewährleisten.

Fazit

Nachdem ykman die Gerätebereitschaft bestätigt und die YKCS11 PKCS#11-Bibliothek in Discover_HSM eingebunden wurde, listet der Sensor X.509-Zertifikate und öffentliche Schlüssel über alle YubiKey PIV-Steckplätze hinweg vollständig schreibgeschützt auf – ohne PIN, ohne privates Schlüsselmaterial – und hält die verwalteten YubiKeys im CBOM Secure-Inventar für die Lebenszyklus- und Compliance-Verfolgung.