全部文章
工程實踐約 4 分鐘閱讀

用 DSSE 與 Ed25519 校驗 Fleet 發布索引

記錄 Fleet Agent、Fleet Desktop 和官網下載頁共用的簽名發布索引格式,以及服務端驗簽與快取的實現細節。

  • Leaflow 工程團隊· Leaflow

Fleet 的客戶端分兩套發布:Fleet Agent 面向 Linux 機器,Fleet Desktop 面向 Windows。兩邊檢查更新時都去 releases.leaflow.net 拿對應的 v1/index.json(比如 /fleet-agent/v1/index.json),解析出 channels.stable.version,再到 dl.leaflow.net 拉實際的安裝包和 SHA-256。Leaflow 官網的下載頁和 /api/download/... 跳轉路由複用了這份索引。

索引檔案本身放在物件儲存裡,經 CDN 分發。只靠 HTTPS 沒法覆蓋儲存桶誤操作、映像被改寫或者 CDN 長時間返回過期快取這些情況,所以我們在索引外層加了簽名,並讓客戶端和官網執行同一套校驗邏輯。

為什麼把索引放進 DSSE 信封

做這層簽名的時候沒往索引 JSON 裡直接塞 signature 欄位。Go(客戶端)和 Node.js(官網)對 JSON 鍵排序、空白符和跳脫字元的預設行為不一樣,硬做 canonical JSON 規範化會多出不少邊界問題;而且裸位元組簽名不帶類型資訊,別處簽出來的東西容易跨場景混用。

我們最後採用了 DSSE(Dead Simple Signing Envelope)v1 格式。外層只有三個欄位,發布流水線把索引 JSON 序列化後轉成 Base64 放進 payload,校驗端先拿原始位元組驗簽,驗簽成功後再 JSON.parse:

fleet-agent/v1/index.json
{
    "payloadType": "application/vnd.leaflow.release-index.v1+json",
    "payload": "eyJwcm9kdWN0IjoiZmxlZXQtYWdlbnQiLC4uLn0=",
    "signatures": [
        {
            "sig": "<base64-ed25519-signature>"
        }
    ]
}

簽名演算法固定用 Ed25519,公鑰在客戶端和官網程式碼裡以 Base64 字串硬編碼,執行時轉成 OKP JWK 交給 Node.js node:crypto 的 verify()(客戶端側對應 Go 標準庫 crypto/ed25519)。簽名的輸入按 DSSE 規範拼成 PAE(Pre-Authentication Encoding),把 payloadType 和解碼後的 payload 分別加上位元組長度字首:

預認證編碼(PAE)
function buildPae(payloadType: string, payloadBase64: string): Buffer {
    const type = Buffer.from(payloadType);
    const payload = Buffer.from(payloadBase64, 'base64');
    return Buffer.concat([
        Buffer.from(`DSSEv1 ${type.length} `),
        type,
        Buffer.from(` ${payload.length} `),
        payload,
    ]);
}

payloadType 寫進了 PAE 的最前面,簽給別處用的信封拿來冒充發布索引,驗簽這一步就會直接失敗。

客戶端與官網的校驗清單

官網在渲染下載頁和響應 /api/download/... 跳轉前,會執行和客戶端一致的校驗流程,任意一步不滿足就拋錯退出:

檢查項對應風險校驗規則
響應體積異常上游響應打滿記憶體響應文字超過 256 KiB(256 << 10)直接丟棄
信封與簽名索引被篡改或偽造payloadType 完全匹配,且至少一條 Ed25519 簽名對得上該產品的固定公鑰
產品欄位拿其他產品的有效簽名索引跨產品替換解碼後的 index.product 與請求的產品名一致
有效期攻擊者或過期快取重放舊版本索引index.expires_at * 1000 大於當前時間戳
產物路徑與校驗值映像路徑跳出目錄或畸形雜湊path 匹配 ^v[\w.+-]+/[\w.+-]+$,sha256 為 64 位小寫十六進位制

公鑰輪換的處理方式

每個產品的公鑰配置寫成字串陣列,驗簽時只要陣列中任意一把公鑰能對上信封裡的任意一條簽名即可:

按產品固定發布公鑰
const RELEASE_KEYS = {
    'fleet-agent': ['<current-ed25519-public-key>'],
    'fleet-desktop/windows': ['<current-ed25519-public-key>'],
} as const;

需要更換發布私鑰時,先給客戶端和官網發一版把新公鑰追加進陣列,同時留著舊公鑰;等活躍版本都帶上新公鑰後,發布流水線切到新私鑰簽發 index.json;舊簽名索引過了 expires_at 以後,下一版再把舊公鑰刪掉。

channels.stable.version 指向哪個版本,頁面和下載介面就取 releases 裡對應的那一項,並將產物相對路徑拼到 mirrors[0] 上。

官網服務端的快取與併發合併

releases.leaflow.net 沒有對瀏覽器開放跨域,索引完全在官網的 Node 服務端讀取,快取間隔設為 300 秒(五分鐘)。

這裡疊了兩層快取。第一層是 Next.js 的 fetch 資料快取(next: { revalidate: 300 })配合 10 秒超時(AbortSignal.timeout(10_000)),和下載頁的頁面重新驗證間隔保持一致。第二層是程序內的 memo():下載介面每次被點選都會呼叫 latestRelease(),併發進來的一批請求會拿到同一個正在執行的 Promise,不會重複去拉索引和反覆做 Ed25519 驗簽。

memo() 在 Promise 拒絕時會立刻刪掉對應的鍵(value.catch(() => entries.delete(key)))。上游抖動或者簽發異常恢復之後,下一個存取 Fleet Agent 下載頁 或 Fleet Desktop 下載頁 的請求就能重新拉到有效索引。

標籤Fleet安全Ed25519發布工程