YubiKey - Arch Linux 中文维基

跳至內容

# YubiKey

出自 Arch Linux 中文维基

相關文章

- 通用第二因素
- OATH
- dm-crypt/加密整個系統
- PAM
- GnuPG
- KeePass
- OpenPGP-card-tools
- Smartcards

翻譯狀態：

- 本文（或部分內容）譯自 YubiKey，最近一次同步於 2025-02-01，若英文版本有所更改，則您可以幫助同步與翻譯更改的內容。
- 您可以在 ArchWiki 的對應頁面找到本文翻譯的原始修訂歷史。
- 本文可能與英文原文存在出入。

YubiKey 是一個小型 USB 安全令牌。取決於型號不同，它可以：

- 作為智慧卡使用（通過 CCID 協議）- 可以存儲 PGP 和 PIV 私鑰
- 處理通用第二因素（U2F）請求
- 存儲和讀取約 30 條開放身份驗證（OATH）憑證
- 以 Yubico OTP 或 HMAC-SHA1 模式處理質詢-應答請求
- 生成一次性密碼（OTP）- 基於 AES 的 Yubico 標準.
- 「輸入」最長 63 個字符的固定密碼

雖然功能豐富，但新版 YubiKey 並不開源。其它替代品有 Solo，TKey 和 Nitrokey。

## 安裝

### 管理工具

- YubiKey Manager — 通過 USB 配置並讀取 YubiKey 的 Python 庫和命令行工具（`ykman`）。帶有可選圖形界面。

  https://developers.yubico.com/yubikey-manager/ || yubikey-manager包，yubikey-manager-qt包
    注意：安裝後，啟用 `pcscd.service`。
    警告：在新的 Arch/python/yubikey-manager 版本上，yubikey-manager-qt包 已經完全無法使用，且 Yubico 已廢棄該工具。

- YubiKey Personalization — 通過 OTP USB 配置並讀取 YubiKey 的庫和工具。比 ykman 更強，但更難用，帶有可選圖形界面。

  https://developers.yubico.com/yubikey-personalization/ || yubikey-personalization包，yubikey-personalization-gui包

### 認證工具

- Yubico PAM — 使用 Yubico OTP 或質詢-應答進行 PAM 用戶認證。

  https://developers.yubico.com/yubico-pam/ || yubico-pam包

- Yubico PAM-U2F — 使用 U2F 進行 PAM 用戶認證。

  https://developers.yubico.com/pam-u2f/ || pam-u2f包

- Yubico Authenticator for Desktop — 通過 USB 從 YubiKey 讀取 OATH 代碼的圖形工具。支持新的 OATH 實現（例如 YubiKey NEO 和 4）和舊版基於槽位的實現（例如 YubiKey Standard 和 Edge）。注意：archlinux/packaging/packages/yubioath-desktop#2

  https://developers.yubico.com/OATH/YubiKey_OATH_software.html || yubioath-desktop包

- Yubico Authenticator 6.0+ for Desktop — Yubico Authenticator 6.0+（6.0 及更高版本）是用於管理 YubiKey 雙因素憑證的工具。從 6.0 版本開始，其使用 Flutter 框架完全重寫。

  https://developers.yubico.com/yubioath-flutter/ || yubico-authenticator-binAUR

- libfido2 — 客戶端側 U2F 支持，使瀏覽器可以通過 U2F 協議使用 YubiKey 進行認證。

  https://developers.yubico.com/libfido2/ || libfido2包

- YubiKey 全盤加密 — 使用質詢-響應模式創建強 LUKS 密碼。支持全盤加密。

  https://github.com/agherzan/yubikey-full-disk-encryption || yubikey-full-disk-encryption包

## 輸入

YubiKey 接受通過 USB 傳入的 API 調用和按鈕輸入。

YubiKey 的按鈕非常靈敏。根據場景不同，觸碰按鈕會出現以下效果之一：

- 觸發固定密碼輸入或一次性密碼（OTP）（短按是槽 1，長按是槽 2）。這是默認行為，很容易會不小心觸發。
- 確認 / 允許功能或訪問，LED 會在這時發光提示用戶。
- 插入 / 彈出智慧卡

## 輸出

YubiKey 會將這些輸入轉換為輸出：

- 按鍵輸入（模擬為 USB 鍵盤），用於輸入固定密碼和 OTP。（注意，固定密碼無法防範鍵盤竊聽器。）
- 內置 LED：
  - 插入時閃爍，方便排障
  - 在需要觸碰按鈕對 API 響應授權時閃爍
- 通過 USB 發送 API 響應，用於：
  - 質詢-響應請求（使用 Yubico OTP 或 HMAC-SHA1 模式進行計算）
  - U2F 質詢-響應請求
  - CCID 智慧卡相關請求

## USB 連接模式

取決於 YubiKey 型號不同，設備提供了最多三種不同的 USB 界面。其中兩種實現了 USB HID（人機互動設備）類，第三種是智慧卡接口（CCID）。三種接口可以分別被啟用或禁用，以控制對應協議。

以下表格展示了接口對應的協議：

協議 | 接口
--- | ---
OTP | 鍵盤 HID
FIDO | 其它 HID
PIV | CCID
OpenPGP | CCID
OATH | CCID

`ykman` 使用了「模式」一詞，將其命名為 OTP、FIDO 和 CCID。

注意：ykman 從 0.6.1（2018-04-16）版本開始將「U2F」改名為「FIDO」。https://developers.yubico.com/yubikey-manager/Release_Notes.html

### 獲取已啟用的模式

對於版本 5 前的 YubiKey：

    $ ykman config mode

    Current connection mode is: OTP+FIDO+CCID

注意：`ykman mode` 命令已被廢棄，後續可能會被移除。

對於 YubiKey 5：

    $ ykman info

    Device type: YubiKey 5 NFC
    Serial number: XXXXXXXXX
    Firmware version: 5.4.3
    Form factor: Keychain (USB-A)
    Enabled USB interfaces: OTP, FIDO, CCID
    NFC transport is enabled.

    Applications    USB     NFC
    FIDO2           Enabled Enabled
    OTP             Enabled Enabled
    FIDO U2F        Enabled Enabled
    OATH            Enabled Enabled
    YubiHSM Auth    Enabled Enabled
    OpenPGP         Enabled Enabled
    PIV             Enabled Enabled

### 配置模式

出廠時所有模式都會被啟用。要修改配置，請使用如下命令：

    $ ykman mode [OPTIONS] MODE

- `MODE` 可以是字符串（如 `OTP+FIDO+CCID`）或是簡寫形式（如 `o+f+c`）。
- `MODE` 也可以是模式編號，編碼了數種啟用的模式。

以下為模式編號表：

0 | 僅作為 OTP 設備
1 | 僅作為 CCID 設備
2 | OTP/CCID 複合設備
3 | 僅作為 U2F 設備
4 | OTP/U2F 複合設備
5 | U2F/CCID 複合設備
6 | OTP/U2F/CCID 複合設備
81 | 僅作為 CCID 設備，附帶觸摸彈出功能

注意：有些範例使用了無效的模式編號 86。80 會被忽略掉，並作為編號 6 使用。

選項：

- `--touch-eject` - 按鈕將用於插入和彈出智慧卡，只在僅 CCID 模式可用，需要禁用 FIDO 和 OTP
- `--autoeject-timeout SECONDS` - 一定時間後自動彈出智慧卡，限制與 `--touch-eject` 相同
- `--chalresp-timeout SECONDS` - 設置質詢-響應超時時間

更多信息請參考 `ykman mode --help`。

## 一次性密碼

該功能的名稱有些誤導，因為它還包括靜態密碼和質詢-響應功能。

該功能有兩個槽位，可以分別通過短按和長按進行訪問。兩者都可以被配置為以下功能之一：

- Yubico OTP
- OATH-HOTP
- OATH-TOTP
- 質詢-響應
- 固定密碼

每個功能在創建時都有多個配置選項，但在創建完成後無法被再次讀取。使用 `ykman otp swap` 可以互換槽 1 和槽 2.

### 出廠配置

對於新出廠的 YubiKey，槽 1 默認配置為 Yubico OTP。該初始 AES 對稱密鑰同時被存儲在 YubiKey 和 Yubico 認證伺服器上，這樣就可以通過 YubiCloud 進行驗證，以在 Yubico 論壇或 https://demo.yubico.com 等使用 Yubico OTP 進行認證。

警告：如果你覆寫掉了槽 1 的出廠密鑰，就無法再次創建同等信任度的新密鑰。出廠生成的 Yubico OTP 憑證以 `CC` 開頭，用戶生成的憑證以 `VV` 開頭。兩者在安全和功能性上沒有區別，但有的服務只信任 `CC` 開頭的憑證。更多信息請參考該論壇帖子。

### Yubico OTP

Yubico OTP 基於對稱密鑰加密。具體來說，每個 YubiKey 都包含了該設備獨有的 AES 密鑰，並同時存儲在驗證伺服器上。當被要求輸入密碼時，YubiKey 將使用如密鑰 ID、計數器和隨機數等不同欄位創建一個令牌，並對結果進行加密。

然後該 OTP 將被發送到目標系統，之後傳到驗證伺服器上。接著，驗證伺服器（其同時擁有私鑰）會將其解密並驗證內容，之後將結果發送到目標系統上，由目標系統決定是否授權。

#### YubiCloud 和驗證伺服器

Yubico 提供了被稱為 YubiCloud 的驗證伺服器，提供了免費無限制訪問。YubiCloud 記錄了所有 YubiKey 的出廠配置，且是 yubico-pam包 等的「默認」驗證服務。Yubico 還提供了伺服器的開源實現。

注意：要驗證 Yubico 驗證伺服器，可以使用：

- HMAC：通過 https://upgrade.yubico.com/getapikey/ 獲取一個 HMAC 密鑰和 ID
- HTTPS：驗證伺服器的證書由 GoDaddy 進行簽名，因此默認受 Arch 信任（前提是至少安裝了 ca-certificates包）。

#### 配置和用法

在槽 2 生成新密鑰，然後上傳到 YubiCloud（會在瀏覽器中打開）：

    $ ykman otp yubiotp --generate-key --upload 2

更多信息請參考 `ykman otp yubiotp --help`。

#### 安全風險

##### AES 密鑰洩漏

可想而知，AES 密鑰必須保密，該密鑰無法從 YubiKey 上被讀取（或者說至少軟體上不可行）。密鑰同時被存放在驗證伺服器上，因此必須確保該伺服器的安全。

##### 篡改驗證請求/響應

鑑於目標系統依賴於驗證伺服器，因此攻擊方式之一是假冒該伺服器。因此，目標系統必須使用 HMAC 或 HTTPS 對驗證伺服器進行驗證。

### 質詢-應答

質詢會發送到 YubiKey，然後基於 secret 計算出應答。同一個質詢會得出相同的應答。就算有大量的質詢-響應對，在沒有 secret 的情況下反推計算操作是不可能的。

這可以被用於：

- 事實上的雙因素認證：質詢被提供給用戶，用戶必須與密碼一起提供正確的響應。雙方都需要持有私鑰。
- 「半」雙因素認證：質詢被用作密碼，然後伺服器會存儲正確的響應。該操作與 OTP 不同，且持有正確響應的人都能獲得授權；但由於不需要私鑰，實現難度較低。

有兩種質詢-響應算法：

- HMAC-SHA1
- Yubico OTP

你可以使用 yubikey-personalization-gui包 通過圖形界面進行配置，也可以遵循以下步驟：

#### HMAC-SHA1 算法

將槽 2 配置為質詢-響應模式，並生成一個密鑰：

    $ ykman otp chalresp --generate 2

可以省略掉 `--generate` 並手動指定密鑰（參考 `ykman otp chalresp --help`），這麼做的好處是可以用同一密鑰配置其它備用設備。可以使用 `openssl rand -hex 20` 生成可用密鑰。

#### Yubico OTP 算法

`ykman` 貌似不支持配置 chal-yubico 算法，但可以使用 `ykpersonalize` 進行配置。在槽 2 生成一個隨機密鑰：

    $ ykpersonalize -2 -ochal-resp -ochal-yubico

更多信息請參考 ykpersonalize(1)。

#### 發送質詢

可以使用 `ykchalresp -slot challenge` 發送質詢並獲得響應，例如：

    $ ykchalresp -2 archie

    12a19763be77d75af46fb76f0b737c117fa47205

將返回特定於槽 2 的 40 字節 SHA1 哈希值。不同的質詢將返回不同的響應。

### 固定密碼

你也可以生成固定密碼：

    $ ykman otp static --generate slot

或者手動提供一個：

    $ ykman otp static slot password

該命令有多個選項：可以設置密碼的長度和字符，也可以設置最後是否會按下確認鍵。具體選項請參考 `ykman otp static --help`。

提示：Most YubiKeys provide only limited (2) slots to save static passwords. A setup challenge-response slot provides static hash responses for unlimited challenges. While these are numeric and lower alphabet only, the response length provides considerable entropy.

### 模擬 USB 鍵盤的限制（又稱「為什麼我的密碼看著很弱？」）

為使 YubiKey 與大多數鍵盤布局兼容，密碼默認只能由 ModHex 字母表（`cbdefghijklnrtuv`）、數字 `0-9` 和 `!` 構成。這些字符在大量鍵盤布局中使用相同的掃描代碼，以確保與大多數計算機兼容。

相關信息可參考 Yubico 提供的白名單。

## OATH

YubiKey 提供了兩種 OATH 實現：

OATH API：新實現，取決於型號不同，可以存儲約 30 個憑證。（YubiKey 4、NEO 及更新版本）
OTP 槽：舊實現，兩個 OTP 槽都分別只能存儲單個憑證。（所有支持質詢-響應的型號都可用）

### OATH API

如果更偏好圖形界面，可以使用 yubioath-desktop包。

`ykman` 可以通過 `ykman oath uri` 以 URI 形式添加代碼。以下為從二維碼圖片添加憑證的示例：

    $ zbarimg qr_code.png --quiet --raw | xargs ykman oath accounts uri

你也可以手動進行添加。配置 TOTP 密鑰，並要求觸摸按鈕後才能生成代碼：

    $ ykman oath accounts add --touch name secret

配置 HOTP 密鑰：

    $ ykman oath accounts add --oath-type HOTP name secret

列出憑證：

    $ ykman oath accounts list

生成代碼：

    $ ykman oath accounts code query

所有可用的子命令請參考 `ykman oath --help`。要查看單個命令的選項，請使用 `ykman oath subcommand --help`。

### OTP 槽實現

在槽 2 中配置 HOTP：

    $ ykman otp hotp 2 key

配置 TOTP：

    $ ykman otp chalresp --totp slot key

生成 HOTP 代碼：

    $ ykman otp calculate slot

生成 TOTP 代碼：

    $ ykman otp calculate --totp slot

另請參考 `ykman otp --help` 和 https://developers.yubico.com/OATH/ 。

## U2F

通過 YubiKey 使用通用第二因素 (U2F) 非常簡單，不需要對密鑰本身進行配置。注意，在部分文檔和工具中，該模式也被稱作「FIDO」。`ykman` 上的管理配置項比較少：

- 設置 PIN 碼：`ykman fido access change-pin`
- 刪除單個憑證：`ykman fido credentials delete QUERY`
- 重置所有憑證和 PIN 碼：`ykman fido reset`

使用 U2F 進行認證的方法請參考 U2F。

另請參考 WebAuthn。

## CCID 智慧卡

CCID（晶片卡接口設備）是一個 USB 標準設備類，適用於 USB 智慧卡讀卡器或類似通過 YubiKey 等通過 USB 連接的安全令牌。HID（人機互動設備）和 CCID 都是 USB 設備類，即它們都位於 USB 標準的同一類別。HID 是類似鍵盤等計算機外設的標準。在 OTP 和 FIDO 模式下，YubiKey 類似於 USB（HID）鍵盤；在使用 PIV 應用或作為 OpenPGP 設備時，會切換到 CCID 協議。

從 2015 年 11 月開始，所有新出廠的 YubiKey 都應默認啟用了 CCID 模式[1]。Enable at least the CCID mode. Please see #獲取已啟用的模式.

### PIV

從 YubiKey NEO 開始，YubiKey 在晶片中內置了 PIV（個人身份驗證）應用。PIV 是一個美國政府標準（FIPS 201），指定了使用 RSA 或 ECC（橢圓曲線密碼學）的令牌如何被用於個人電子身份認證。YubiKey NEO 只支持 RSA 加密，後續型號（包括 YubiKey 4 和 5）支持 RSA 和 ECC，具體支持的算法取決於固件。例如，只有 5.7 及更新版本的 YubiKey 支持 RSA 3072、RSA 4096、Ed25519 和 X25519 密鑰[2]。PIV 令牌的特性是可以保護私鑰並在晶片片上執行操作，私鑰在安裝到令牌上後就無法被導出。私鑰也可以通過晶片內置的隨機數生成器直接在晶片上生成，在這種情況下，私鑰完全不會暴露出晶片外，也無法從令牌上恢復。在使用 PIV 特性時，YubiKey 是作為 CCID 設備工作的。

### OpenPGP 智慧卡

YubiKey 可以作為標準 OpenPGP 智慧卡工作，具體搭配 GnuPG 進行配置和使用的步驟請參考 GnuPG#智慧卡。Yubico 也提供了一些文檔：https://developers.yubico.com/PGP/ 。

如果你不想使用其它功能（如 U2F 和 OTP），可以將按鈕配置為插入和彈出智慧卡，也可以配置自動彈出時間。具體信息請參考 #USB 連接模式。

默認用戶 PIN 碼是 `123456`，默認管理員密碼和 PUK 是 `12345678`。別忘了改掉這三個密碼。

## 用例

本節展示了如何使用 YubiKey 進行多種身份驗證，實際上能做到的比這還多。

### 使用 LUKS 進行全盤加密

有數種實現方案：

- 質詢-響應：將對質詢的響應用作 LUKS 密鑰。質詢可被用作雙因素認證中的密碼，也可為單因素認證以純文本形式存儲。
- GnuPG：使用 Yubikey 的 PGP 智慧卡功能，在不需要強密碼的同時提供強雙因素認證。
- FIDO HMAC Secret：如果擬定 YubiKey 支持 U2F，可讓其返回對稱 secret。

注意：硬碟的加密安全性僅與其最弱的密鑰等同。在配置完這幾項之一後，考慮移除初始密碼或替換為超長密碼。

#### 常見依賴

- 一個可啟動的 LUKS 加密系統，使用 `encrypt` mkinitcpio 鉤子，並有至少一個可用槽位。
  - mkinitcpio-ykfdeAUR 除外，`sd-encrypt` 鉤子不受上述任一方案支持。
- 備份 LUKS header（可選，但建議）

#### 質詢-應答

完整步驟請參考 yubikey-full-disk-encryption包 的官方文檔。簡單來講：

1. 安裝 yubikey-full-disk-encryption包
2. 配置 `/etc/ykfde.conf`
3. 註冊硬碟：`# ykfde-enroll -d /dev/DISK -s LUKS_SLOT`
4. 在 `encrypt` 鉤子前添加 `ykfde` mkinitcpio 鉤子
5. 重新生成 initramfs

  注意：對於 Plymouth 用戶：將 `plymouth-encrypt` 替換為 `ykfde` 鉤子。

該方案有數個變種：

- 2FA：默認行為，在註冊設備和啟動時需要將質詢作為密碼提供.
- 1FA：在 `ykfde.conf` 中設置 `YKFDE_CHALLENGE`。注意，這是以純文本保存的，請考慮為該文件禁用非根用戶讀取權限。
- NFC 支持（實驗性）
- 待機和喚醒支持（實驗性）在待機時自動鎖定加密卷，恢復時解鎖

為使配置生效，需要重新生成 initramfs。

#### 基於 systemd 的 initramfs

`sd-encrypt` 鉤子的用戶可以安裝 mkinitcpio-ykfdeAUR 或 mkinitcpio-ykfde-gitAUR，然後遵循項目文檔中的操作描述。具體步驟與 yubikey-full-disk-encryption包 大致類似。

#### GnuPG encrypted keyfile

One tool to accomplish this is initramfs-scencrypt; see its docs for complete instructions. Note that as of October 2022 this package is not in the AUR and is not thoroughly tested, though the GitHub repository offers a PKGBUILD.

The dm-crypt pages offer a few alternatives, though they are mostly links to old forum posts.

#### HMAC secret extension of FIDO2 protocol

Yet another way of using YubiKey for full disk encryption is to utilize HMAC Secret Extension to retrieve the LUKS password from YubiKey. This can be protected by a passphrase. This functionality requires at least YubiKey 5 with firmware 5.2.3+. For a passphrase protected solution, install khefinAUR and follow instructions available in project documentation. For single factor (optionally PIN-protected) solution and starting with systemd 248, it is possible to use your FIDO2 key as LUKS2 keyslot. Instructions available in the author's blog post.

### KeePass

可以為 KeePass 配置 YubiKey 支持，具體步驟請參考 YubiKey 一節。

### SSH 密鑰

#### CCID

如果你的 YubiKey 支持 CCID 智慧卡，可以基於 GPG 或 PIV 密鑰將其用作基於硬體的 SSH 密鑰。Yubico 提供了詳細的文檔：

- 兩者用途和優缺點的概述
- Instructions for PGP 認證
- Instructions for 通過用戶證書進行 PIV 認證
- Instructions for 通過 #PKCS11 進行 PIV 認證

  注意：YubiKey 的 PIV 應用默認 PIN 碼是 `123456`，你可能會想修改它和默認管理密碼。詳細信息請參考設備配置方法。

#### U2F

你也可以通過 YubiKey 的 U2F 功能創建基於硬體的 SSH 密鑰。具體步驟請參考 SSH 密鑰#FIDO/U2F。

#### PIV

yubikey-agentAUR 以 PIV 令牌的顯示存儲 SSH 密鑰。配置步驟請參考 https://github.com/FiloSottile/yubikey-agent#readme 。

### 使用 PAM 進行 Linux 用戶認證

PAM 及所有使用 PAM 進行用戶驗證的軟體都可使用 YubiKey 作為用戶驗證的一環，其中包括 sudo、su、ssh、鎖屏、顯示管理器及幾乎所有 Linux 系統上需要對用戶進行驗證的地方，靈活的配置項使你可以為整個系統、特定應用或一組應用設定認證需求。例如，你可以在本地會話上用 YubiKey 取代密碼，但在遠程會話上要求同時使用二者。除了 Arch Wiki 外，建議額外閱讀 pam(8) 和 pam.conf(5) 來理解工作原理的配置方法。

有多個模塊可用於將 YubiKey 支持的協議集成到 PAM 中：

- pam-u2f包 - 通過 FIDO2 標準支持 #U2F。如果你不確定要用哪種，建議用這個
  - 通用第二因素#用於用戶會話認證
  - Yubico 的官方文檔，提供了支持的模塊參數清單
  - Man Page：pam_u2f(8), pamu2fcfg(1)
- oath-toolkit包 - 提供 #OATH 一次性密碼支持（HOTP 或 TOTP）
  - pam_oath
- yubico-pam包 - 提供 #Yubico OTP 和質詢-響應支持。注意，Yubico OTP 模式需要聯網到驗證伺服器，而質詢-響應模式沒有網絡要求
  - Yubico 的官方文檔
  - pam_yubico(8) - 注意 `mode` 參數，需要用於配置質詢-響應模式

警告：修改 PAM 配置文件需要小心，錯誤配置會導致系統不再安全，又或是過於安全使得無法通過認證。

PAM 配置超出了本文討論範圍，大致描述如下：

- 在用戶 home 目錄下或中心化創建包含密鑰的文件
- 在對應 PAM 配置文件的合適位置添加一行，格式如下：

       auth [required|sufficient] [module_name].so [module arguments]

- 對於多因素認證使用 `auth required`，單因素認證使用 `auth sufficient`
- `module_name` - 例如：`pam_u2f.so`。要獲取已安裝的模塊清單，請執行：`ls /usr/lib/security`
- 模塊配置參數用於如指定密鑰位置、模塊在認證時使用的方法等操作。

#### SSH 附註

- Yubico 提供了一些額外說明。雖然是寫給舊版 Ubuntu 的，但在最新的 Arch 系統上也可用。
- 如果你在為遠程系統配置使用 YubiKey，需要至少額外提供一個備份 SSH 會話，以免配置失敗時被鎖在系統外。
- 檢查 `/etc/ssh/sshd_config` 是否包含以下設置。openssh包 提供的 `sshd_config` 默認包含以下正確配置。

       ChallengeResponseAuthentication no
       UsePAM yes

### 瀏覽器/網頁集成

很多網頁服務都開始支持 FIDO 硬體令牌。詳細信息請參考 U2F 和 WebAuthn，但通常只需要安裝 libfido2包，然後就可以嘗試一下。

## 小技巧

### 在插入/拔出 YubiKey 時執行操作

例如，如果你想在拔出 YubiKey 時執行操作，可以創建 `/etc/udev/rules.d/80-yubikey-actions.rules` 並添加以下內容：

    ACTION=="remove", ENV{ID_VENDOR}=="Yubico", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0010|0111|0112|0113|0114|0115|0116|0401|0402|0403|0404|0405|0406|0407|0410", RUN+="/usr/local/bin/script args"

注意，有些版本的 YubibKey 可能無法使用該示例，你需要看下 lsusb 的 vendor 和 model ID 及設備描述，也可以用 udevadm 來獲取這些信息。如果要改成在插入時執行，需要將 ACTION 中的 remove 改成 add。

### 在插入時啟動 Yubico Authenticator

The authenticator is a long-running GUI process. If run directly in a udev rule, the process would block udev's processing. If forked, udev would unconditionally kill the process after the event handling finishes. Thus you can't start the authenticator from udev rules. However, systemd.device may be used to handle this case.

與上文類似，創建 `/etc/udev/rules.d/80-yubikey-actions.rules` 並添加以下內容：

    ENV{ID_VENDOR}=="Yubico", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0010|0111|0112|0113|0114|0115|0116|0401|0402|0403|0404|0405|0406|0407|0410", SYMLINK+="yubikey", TAG+="systemd"

然後創建一個 systemd 用戶單元：

    ~/.config/systemd/user/yubioath-desktop.service

    [Unit]
    Description=Autostart Yubico Authenticator
    # Uncomment if you want to stop the authenticator when unplugged.
    #StopPropagatedFrom=dev-yubikey.device

    [Install]
    WantedBy=dev-yubikey.device

    [Service]
    Type=oneshot
    ExecStart=/usr/bin/yubioath-desktop

並將其啟用。systemctl 會提示它被添加為不存在單元的 `dev-yubikey.device` 依賴，但對應單元會在 YubiKey 插入時創建。

## 維護 / 升級

### Installing the OATH Applet for a YubiKey NEO

These steps will allow you to install the OATH applet onto your YubiKey NEO. This allows the use of Yubico Authenticator in the Google Play Store.

注意：These steps are only for NEOs with a firmware version <= 3.1.2. The current generation NEOs (with U2F) come with the OpenPGP applet already installed)

#### Configure the NEO as a CCID device

1. Install yubikey-personalization-gui包 (yubikey-personalization-gui-gitAUR).
2. Add the udev rules and reboot so you can manage the YubiKey without needing to be root
3. Run `ykpersonalize -m82`, enter `y`, and hit enter.

#### Install the applet

1. Install gpshellAUR, gppcscconnectionpluginAUR, globalplatformAUR, and pcsclite包.
2. 啟動 `pcscd.service`.
3. Download the most recent CAP file from the ykneo-oath site.
4. Download `gpinstall.txt` from GitHub.
5. Edit the line in gpinstall.txt beginning with `install -file` to reflect the path where the CAP file is located.
6. Open a terminal and run `gpshell path/to/gpinstall.txt`.
7. Ideally, a bunch of text will scroll by and it ends saying something like

       Command --> 80E88013D7C000C400BE00C700CA00CA00B400BE00CE00D200D500D700B000DB00C700DF00BEFFFF00BE00E400AC00AE00AE00DB00E700A
       A00EA00ED00ED00ED00BE00EF00F100F400F100F700FA00FF00BE00F700AA01010103010700CA00C400B400AA00F700B400AA00B600C7010C
       010C00AA0140012001B0056810B0013005600000056810E0011006B4B44304B44404B44106B44B4405B443400343B002410636810E06B4B44
       407326810B004B43103441003334002B102B404B3B403BB4003B440076820A4100221024405B4341008B44600000231066820A100
       Wrapped command --> 84E88013DFC000C400BE00C700CA00CA00B400BE00CE00D200D500D700B000DB00C700DF00BEFFFF00BE00E400AC00AE00AE00DB00E700A
       A00EA00ED00ED00ED00BE00EF00F100F400F100F700FA00FF00BE00F700AA01010103010700CA00C400B400AA00F700B400AA00B600C7010C
       010C00AA0140012001B0056810B0013005600000056810E0011006B4B44304B44404B44106B44B4405B443400343B002410636810E06B4B44
       407326810B004B43103441003334002B102B404B3B403BB4003B440076820A4100221024405B4341008B44600000231066820A15D848CB77
       27D0EDA00
       Response <-- 009000
       Command --> 80E60C002107A000000527210108A00000052721010108A000000527210101010003C901000000
       Wrapped command --> 84E60C002907A000000527210108A00000052721010108A000000527210101010003C9010000B4648127914A4C7C00
       Response <-- 009000
       card_disconnect
       release_context

8. Unplug the NEO and try it with the Yubico Authenticator app.

#### （可選）安裝 Yubico Authenticator 桌面客戶端

You can get the desktop version of the Yubico Authenticator by installing yubioath-desktop包.

While `pcscd.service` is running, run `yubioath-desktop` and insert your YubiKey when prompted.

## 排障

不論部分功能正常與否，先重啟試試，特別是如果上次 YubiKey 能正常使用後更新過系統。

### YubiKey not acting as HID device

注意：These steps are no longer necessary after systemd since v244 added native support for this functionality.

Add udev rule as described in this article:

    /etc/udev/rules.d/10-security-key.rules

    KERNEL=="hidraw*", SUBSYSTEM=="hidraw", MODE="0664", GROUP="users", ATTRS{idVendor}=="2581", ATTRS{idProduct}=="f1d0"

Run `udevadm trigger` afterwards.

### ykman 無法連接到 YubiKey

如果管理器無法連接到 YubiKey，先檢查 `pcscd.service` 或 `pcscd.socket` 是否已經啟動。

### Error: Failed connecting to YubiKey 5 [OTP+FIDO+CCID]. Make sure the application have the required permissions.

在 `scdaemon` 獨占了 YubiKey 控制權的情況下，如果 `ykman` 嘗試讀取 OATH 憑證，就會出現該報錯。[3]

要修復該問題，可以在 `~/.gnupg/scdaemon.conf` 中為設備配置 `reader-port` 選項。[4]

注意：該操作會導致每次 ykman 訪問 YubiKey 時 gpgagent 都會提示你解鎖 YubiKey。

對於 YubiKey NEO 和 YubiKey 4：

    reader-port Yubico Yubikey

對於 YubiKey 5：

    reader-port Yubico Yubi

### 無法將 YubiKey 綁定到虛擬機

假設 YubiKey 可用於虛擬機上，該問題是由宿主機上的驅動綁定了設備導致的。要解綁設備，需要在宿主機上通過 dmesg 獲取總線和埠信息：

    # dmesg | grep -B1 Yubico | tail -n 2 | head -n 1 | sed -E 's/^\[[^]]+\] usb ([^:]*):.*/\1/'

輸出的 USB ID 格式為 `X-Y.Z` 或 `X-Y`。接著，在宿主機上使用 `find` 搜索 `/sys/bus/usb/drivers` 來查找哪一個驅動在占用 YubiKey（例如 `usbhid` 或 `usbfs`）：

    $ find /sys/bus/usb/drivers -name "*X-Y.Z*"

要解綁 YubiKey，需用到之前獲取的信息（例如 `/sys/bus/usb/drivers/DRIVER/X-Y.Z:1.0`）：

    # echo 'X-Y.Z:1.0' > /sys/bus/usb/drivers/DRIVER/unbind

### Error: [key] could not be locally signed or gpg: No default secret key: No public key

在插入 YubiKey 時使用非標準密鑰環對密鑰進行簽名時出現（如 Pacman 的 `pacman-key --populate` 命令）。解決方法是拔出 YubiKey 後重試。

### YubiKey 在 Yubico Authenticator 中消失後又重新出現

這是因為缺少 CCID 驅動，你需要安裝 ccid包。

### YubiKey core error: timeout

可能是用錯槽位了，換一個試試。

分類：​

- OpenPGP
- Smartcards
- 通用第二因素

YubiKey
新增話題