在 Windows 上使用 Git 與 YubiKey

大家總是會有在 Windows 上開發程式的需求,因此在 Windows 上使用 Git 也是常有的事。不過許多在 Linux 上理所當然存在的事物不能直接搬到 Windows,比如說支援 PKCS#11 與智慧卡驗證功能的 SSH client。因此如果你在 YubiKey 上儲存了私鑰,然後想拿它來存取遠端的 SSH Git server,就會遇上一些麻煩。

這邊趁著還有記憶的時候寫一下在 Windows 上的操作步驟。如果你不知道 YubiKey 是什麼,可以參考我之前寫的這篇文章

1. 安裝 OpenSC

OpenSC wiki 上有 MSI 載點,由於我們需要搭配 32bit 的 SSH agent 使用,因此你必需安裝 win32 的版本。

2. 下載 Putty SC

Putty 是 Windows 上相當知名的 SSH client,而 Putty SC 是修改過的 Putty 版,支援使用 PKCS#11 進行智慧卡驗證的功能。但我們需要的其實並不是用它來連接 Git server,而是讓它扮演 SSH agent 的角色。

首先插入你的 YubiKey,並執行下載回來的 puttysc.exe,你會看到一個與以往幾乎完全相同的 putty 介面,但是點開左邊的 Connection → SSH → Pkcs11 後,可以額外設定 PKCS#11 函式庫的位置:

Putty SC

請把 Attempt "PKCS#11 smartcard" auth (SSH-2) 打勾,並且在下面的 PKCS#11 library 中填入 OpenSC 所提供的 PKCS#11 函式庫路徑。如果你使用 MSI 傻瓜式安裝,它的路徑應該是 C:\Windows\SysWOW64\opensc-pkcs11.dll

設定完函式庫路徑後,點選 token label 應該會出現 PIV_IPIV_II 之類的選項。如果你在 YubiKey 內儲存了多支私鑰,這邊就可以選擇要使用哪一支鑰匙來進行 SSH 認證。

設定好之後,點選左邊最上面的 Session 並把剛才做的設定儲存至 Default settings。

3. 執行 SSH Agent

在剛才的 Putty SC 還有另一個檔案 pageantsc.exe,請在設定完 Putty SC 後執行這支程式。

這是個 SSH agent,它的任務是管理 SSH 私鑰,在 SSH client 需要進行驗證時提供必要的加解密及簽章驗證服務。只要你把 YubiKey 插在電腦上執行 pageantsc.exe,桌面右下角的系統圖示中就會出現一台帶著帽子的電腦。按右鍵點選 View Keys 就可以發現它已經偵測到 YubiKey 中的私鑰。

pageantsc 偵測到的私鑰列表

4. 下載 plink.exe

plink.exe 命令列下的 SSH 連線工具,Git 可以透過它來連接遠端的 SSH server。Putty SC 的作者並沒有提供支援智慧卡版本的 plink,不過這無所謂,因為官方版的 plink 可以連接本地端的 SSH agent 進行金鑰驗證,而我們剛才已經把 SSH agent 設定好了。

因此我們要做的就只是下載 Putty 官方網頁 上的 plink.exe 即可。

下載後隨便放在哪都可以,但你要新增一個環境變數 GIT_SSH 指向它的路徑,這樣 Git 才知道存取 SSH server 時要呼叫 plink:

設定 GIT_SSH 環境變數

5. 開始使用 Git

做到這步你可能有點暈了,這些工具彼此之間的關係如下:

古代印度人認為世界由三頭大象支撐,而大象又站在巨龜上...(以下略)

串了這麼多工具程式,現在 Git 已經可以使用 YubiKey 上面的私鑰進行 SSH 驗證了!把 YubiKey 插在電腦上,在命令列中執行 git clone 時,SSH agent 就會要求你輸入 PIN 碼,表示它正在試圖使用 YubiKey 中的私鑰進行運算:

git clone

即使是在 Visual Studio Code 內建的 Git 也沒有問題:

Visual Studio Code

注意事項

執行完 pageantsc.exe 後,你可能以為可以先把 YubiKey 拔下來,要用時再插回去就好。可惜這世界沒有那麼美好,當你拔掉重插後,若不重新執行 pageantsc.exe 就無法順利進行 SSH 私鑰驗證。

弄了這麼久用起來還是很麻煩,實在有種徒勞無功的搞笑感。

分享到 評論