十一、附錄：憑證與金鑰全景¶
這章在講什麼：整套系統一共有哪些憑證（電子身分證明，用來證明「我是誰」的一份電子檔）與金鑰、各自放在哪、換掉會影響什麼、缺了會出現什麼症狀。
先用一個比喻抓住全貌：憑證就像門禁卡。持卡人要向讀卡機證明「我是誰」，讀卡機也要向持卡人證明「這是對的那扇門」——兩邊都要對得上才放行。平台與 Agent 之間就是這樣互相驗證的。而發卡的那個單位（CA，憑證頒發機構，替其他憑證背書的「發證單位」）自己也有一張卡，用來替所有卡片背書。
一般安裝維護不需要讀這一章。 所有憑證都是安裝過程自動處理的，正常運作下貴單位不需要準備、也不需要輸入任何憑證。這一章是給資安審查人員、負責憑證管理的 IT 人員、以及需要深入排錯的維運人員看的。
什麼時候看：資安審查要回答「你們的金鑰怎麼管的」時、平台要換憑證時、或排錯查到憑證這一層時。
怎麼讀：先讀 11.1 那張圖——那是整章的地圖。看懂「三個世界互不相干」這件事，後面每一節就都對得上位置了。
11.1 三個互不相干的信任世界¶
先說結論：這裡的憑證分屬三個彼此獨立的信任體系，用途完全不同、不可互換。 這是整章最容易混淆、也最容易踩錯的一點。
三個世界各自回答一個不同的問題：
┌──────────────────────────────────────────────────────────────┐
│ ① 產品簽章世界 — 「這份程式是原廠出的、沒被改過嗎」 │
│ 原廠簽發私鑰（不在客戶端） → 產品內硬編公鑰 → 驗程式清單簽章 │
├──────────────────────────────────────────────────────────────┤
│ ② Agent 通訊 PKI 世界 — 「平台與 Agent 互相認得對方嗎」 │
│ 平台內部 CA → 簽 Agent 憑證、簽平台用戶端憑證；另有一組簽章金鑰 │
├──────────────────────────────────────────────────────────────┤
│ ③ Web TLS 世界 — 「Agent 連的是真的平台嗎」 │
│ 平台的 https 憑證 → Agent 在安裝時確認指紋後存成信任檔 │
└──────────────────────────────────────────────────────────────┘
用白話再講一次這三個世界：
- ① 產品簽章世界：確認「軟體本身沒被動過手腳」。跟門禁無關，比較像商品上的防拆封條。客戶端完全不用管。
- ② Agent 通訊 PKI 世界：這才是門禁卡的世界。平台與 Agent 互相刷卡認人，發卡單位是平台自己的內部 CA。客戶端唯一要做的事是備份。
- ③ Web TLS 世界：Agent 主動連出去找平台時，確認「對面真的是我們的平台」，不是別人假冒的。客戶端只在安裝時人工核對一次指紋。
私鑰／公鑰是成對的兩把鑰匙：私鑰自己收好絕不外流，公鑰可以公開給任何人。用私鑰蓋的簽章（電子印章），別人拿公鑰就能驗真偽——但沒有私鑰就偽造不出來。
PKI 是「用一個發證單位替一群憑證背書」的整套架構，②那一整層就是。
三者沒有任何關聯。 最常見的誤解是把 ② 的內部 CA 憑證（ca.crt）拿去當 ③ 的平台信任檔用——那兩者毫無關係，換錯了會出現「憑證驗證失敗」而症狀完全不指向真因。
11.2 ① 產品簽章世界¶
在解決什麼：確認客戶手上跑的 Agent 程式確實是原廠出的、且出貨後沒有被改動。
客戶端要不要做事：完全不用。 這一層沒有任何需要貴單位管理的憑證，讀這一節只是為了知道它存在、以及看懂它報錯時代表什麼。
細節一覽¶
| 項目 | 內容 |
|---|---|
| 簽發私鑰 | 由原廠保管，永遠不在客戶端。每個發行環境各有一把（各自有不同的識別碼） |
| 驗證公鑰 | 編譯進 Agent 執行檔內，不是外部檔案 |
| 被簽的東西 | 程式檔案清單（每個檔案的 SHA-256）＋清單的簽章 |
| 驗證時機 | Agent 每次啟動時，逐檔比對 |
| 驗不過的行為 | 拒絕啟動，記錄印出完整的不符清單 |
雜湊 SHA-256 是一種算「檔案指紋」的方法：內容只要差一個位元，算出來的指紋就完全不同。清單記的就是每個檔案的指紋。
為什麼公鑰要編譯進程式¶
如果驗證用的公鑰是一個外部檔案，動手腳的人只要：產一把自己的金鑰 → 用它重簽一份改過的清單 → 把公鑰檔換成自己的——整道驗證就對他完全放行，而且每一步都不需要特殊權限。
編譯進去之後兩者互鎖：想改程式要先過驗章，想改驗章要先改程式（而程式本身也在清單內）。
缺件症狀¶
| 您看到的訊息 | 意思 |
|---|---|
啟動時 [FATAL] 產物完整性驗證未通過 |
程式被改動過，或出貨包在傳輸中損壞 |
| 安裝時「映像檔內容與出貨清單不符」 | 出貨包本身損壞或被替換 |
🔴 這兩種情形都不要嘗試繞過。 重新取得原廠出貨包，並聯繫原廠說明狀況。
11.3 ② Agent 通訊 PKI 世界¶
在解決什麼：平台與 Agent 之間的雙向身分確認。這就是前面說的「兩邊都要刷卡」那一層。
客戶端要不要做事：正常情況什麼都不用做——Agent 端這一層的東西全部是註冊時自動取得的。唯一要做的是備份，見本節末。
一個落地站一組。 平台端的這組金鑰在平台安裝時產生，該平台底下所有 Agent 共用同一組信任根。
這個世界一共有四件東西。
一覽表¶
| # | 名稱 | 誰產生 | 放在哪 | 效期 | 換掉的影響 |
|---|---|---|---|---|---|
| 1 | 內部 CA（憑證＋私鑰） | 平台安裝時 | 平台主機的資料目錄下 pki/agent/ca.crt、ca.key |
10 年 | 🔴 全部 Agent 必須重新註冊 |
| 2 | Agent 憑證（每台一張） | Agent 註冊時由 CA 簽發 | Agent 的 agent-certs 資料區內 agent.crt（私鑰 agent.key 由 Agent 自己產、永不外送） |
10 年 | 該台重新註冊即可 |
| 3 | 平台用戶端憑證 | 平台安裝時（由 CA 簽） | 平台主機 pki/agent/cloud_client.crt、cloud_client.key |
10 年 | 換發後平台需重啟；Agent 端不受影響 |
| 4 | 通行證簽章金鑰對 | 平台安裝時 | 平台主機 pki/agent/jwt_private.pem（私鑰）；公鑰於註冊時下發到 Agent 的 jwt_public.pem |
無到期 | 🔴 全部 Agent 必須重新註冊（要重新拿公鑰） |
平台端這六個檔的權限：私鑰
600、憑證與公鑰644，全部歸屬 uid 1000（平台服務以該身分讀取）。權限或擁有者不對的症狀是「Agent 註冊回 500」——平台安裝程式每次執行都會重設一次，不需要手動處理。
各自在做什麼¶
1. 內部 CA — 這個信任世界的根，也就是那個「發卡單位」。它簽出 2 與 3，讓平台與 Agent 互相認得對方。
2. Agent 憑證 — Agent 對平台證明「我是那台註冊過的機器」，等於 Agent 這一側的門禁卡。私鑰在 Agent 首次啟動時本機產生，只把憑證簽署請求送去平台，私鑰從來不離開這台機器。憑證的主體名稱綁定安裝時填的「本機對外位址」——這也是為什麼改那個位址需要重新註冊。
3. 平台用戶端憑證 — 平台回頭取證據檔時，對 Agent 證明「我是那個平台」，等於平台那一側的門禁卡。沒有它，Agent 的 8443 一律拒絕連線。
4. 通行證簽章金鑰對 — 平台每次取證據檔會現簽一張效期 60 秒的通行證（JWT）：一張短效的電子通行證，上面寫明「誰、可以取哪個檔、有效到幾點」，並綁定那一台 Agent 的設備指紋。Agent 用註冊時拿到的公鑰驗證。短效是刻意的：Agent 一旦被撤銷，幾乎立即失效。
⚠️ 這對金鑰必須是 RSA（一種加解密演算法；RS256 是它搭配 SHA-256 的簽章方式）。兩端都寫死使用 RS256 演算法，用了其他類型的金鑰在註冊與心跳階段完全不會報錯（那兩個階段不用簽章），一路正常到「第一次下載證據檔」才失敗——排查成本極高。這一項由平台安裝程式自動處理，手動架設平台環境時才需要留意。
客戶端要做什麼¶
正常情況什麼都不用做——Agent 端這四件東西全部是註冊時自動取得的，貴單位不需要準備、也不需要輸入任何憑證。
唯一需要注意的是備份：Agent 的 agent-certs 資料區存的就是這台機器的身分。備份方式見 5.6。
🔴 平台端也要備份。 平台主機資料目錄下的
pki/agent/整個目錄（上表第 1、3、4 項）不在平台的兩份設定檔內，是獨立目錄，備份時最容易漏掉——遺失的話所有已註冊的 Agent 會全部離線且必須逐台重新註冊。請提醒平台的維運人員一併納入備份（落地部署版的維運手冊第四章有對應說明）。
缺件症狀對照¶
| 症狀（在哪看到） | 缺的是什麼 |
|---|---|
Agent 記錄：雲端 register 未回傳憑證 |
平台端沒開啟 Agent 對接設定，或平台缺 CA／金鑰 |
Agent 記錄：data-plane TLS not started: certificate not ready |
還沒註冊成功，第 2 項尚未簽回 |
平台端下載證據檔失敗，Agent 回 400 No required SSL certificate |
平台缺第 3 項（用戶端憑證），或平台設定後沒重啟 |
| 平台端下載證據檔回 401 | 通行證問題：金鑰不對、或主機時鐘偏差（見 10.4） |
| 平台端下載證據檔回 401 且訊息提到指紋 | 憑證被搬到別台機器上使用，或那台機器的設備指紋變了 |
11.4 ③ Web TLS 世界¶
在解決什麼：Agent 連出去的時候，確認「對面真的是我們的平台」，而不是被導去一台假冒的。
客戶端要不要做事：只有安裝當下要做一件事——由現場的人跟平台管理者核對一次憑證指紋。核對完就存起來，之後不用再管，除非平台換憑證。
| 項目 | 內容 |
|---|---|
| 平台 https 憑證 | 平台端持有。落地部署的平台通常是安裝時產生的自簽憑證 |
| Agent 端的信任檔 | 安裝時經人工確認指紋後存下的那張，落在 /srv/guidant-ai-agent/certs-in/cloud-ca.pem |
| 效期 | 依平台憑證而定（自簽憑證通常為 10 年） |
| 換掉的影響 | 🔴 平台換 https 憑證後，所有 Agent 都連不上，需逐台更新信任檔 |
自簽憑證是自己替自己開的身分證明，沒有外部發證單位背書。憑證指紋是這張憑證的摘要值，短短一串，用來讓人逐字核對「兩邊看到的是不是同一張憑證」。
為什麼要人工確認指紋¶
自簽憑證無法由公認的憑證機構驗證，所以第一次連線時沒有任何自動的方法判斷「這張憑證是不是真的屬於貴單位的平台」。
作法跟第一次用 SSH 連新伺服器時確認金鑰指紋完全一樣：由安裝現場的人，向平台管理者核對一次指紋，確認後就存下來當作日後的驗證依據。
🔴 沒有「略過憑證驗證」的選項，而且是刻意的。 指紋確認取代的是「盲目信任」，不是取代「驗證」本身。指紋不符時安裝會中止且不對機器做任何變更——這是正確的行為，不是故障。
平台使用公認憑證機構簽發的憑證時，這一步不會出現，Agent 走系統內建的憑證信任清單即可。
11.5 平台更換 https 憑證後怎麼辦¶
症狀：所有 Agent 同時失聯，記錄裡是 CERTIFICATE_VERIFY_FAILED。
先說結論：這件事不難，也不會掉資料。 在每一台 Agent 主機上重跑一次安裝、重新核對一次新指紋就好。
這步在做什麼：重跑安裝，讓它去平台重新抓一次憑證，並請您確認新的指紋。
成功長什麼樣：畫面出現指紋確認提示，核對無誤後確認，安裝流程跑完，Agent 恢復連線。
資料完全不動，Agent 也不需要重新註冊（②世界的憑證仍然有效）。
平台換憑證前請先知會 Agent 的維運人員，並準備好新憑證的 SHA-256 指紋供現場核對。若貴單位有多台 Agent，建議安排在同一個維護時段一起更新。
11.6 一張表看完「換了什麼要做什麼」¶
上面幾節分開講，這裡把所有情況併成一張表。要判斷「這個變動要不要做事、會不會掉資料」，看這張就夠了。
| 換了這個 | 要做什麼 | 資料會不會掉 |
|---|---|---|
| Agent 主機的 IP／對外位址 | 重跑 sudo ./install.sh 改第 3 題 |
不會 |
| Agent 的顯示名稱 | 重跑 sudo ./install.sh 改第 4 題 |
不會 |
| Agent 版本（升級） | sudo guidant-agent-compose upgrade <包> |
不會 |
| Agent 主機重灌作業系統 | 設備指紋會變，平台自動更新該列並記稽核事件；若資料區也沒了則需重新註冊 | 資料區沒備份就會掉 |
| Agent 主機換主機板／搬虛擬機 | 同上 | 同上 |
| 平台的 https 憑證 | 逐台 Agent 重跑安裝確認新指紋（11.5） | 不會 |
| 平台的內部 CA | 🔴 全部 Agent 重新註冊（步驟見 10.6） | 不會（但要重新註冊） |
| 平台的通行證簽章金鑰 | 🔴 全部 Agent 重新註冊（要重新取得公鑰） | 不會 |
| 平台的用戶端憑證 | 平台端重啟即可，Agent 不受影響 | 不會 |
| 原廠的產品簽發金鑰 | 客戶端無感（新版出貨包自然帶新簽章） | 不會 |
11.7 給資安審查的重點摘要¶
資安審查最常問的問題，答案整理在這裡。
| 問題 | 回答 |
|---|---|
| 出貨包內含任何預設憑證或密碼嗎 | ❌ 沒有。所有憑證與密碼都在貴單位主機上、於安裝當下生成 |
| 有跨客戶共用的私鑰嗎 | ❌ 沒有。每個落地站的 PKI 各自獨立 |
| Agent 的私鑰會離開這台機器嗎 | ❌ 不會。本機產生、只送出憑證簽署請求 |
| 平台取證據檔的授權有時效嗎 | ✅ 有。每次現簽、效期 60 秒，且綁定該台的設備指紋 |
| Agent 被入侵時能立即切斷嗎 | ✅ 可以。平台端「撤銷」該台，所有呼叫立即拒絕，不需碰那台機器 |
| 受測機的稽核帳號憑證怎麼保管 | 平台端加密存放、派工當下才解密下發、Agent 端用完即刪不落地。詳見 2.6 |
| 設定檔為什麼是明文 | 服務啟動時必須拿到可用的密碼，加密儲存只是把問題換一個檔名。真正的防線是檔案權限（600 + root）。同型產品做法一致 |
| 證據檔能保證不可竄改嗎 | 改動必被偵測（平台端保有雜湊錨點）；但不宣稱「不可刪除」或 WORM——儲存跑在貴單位機器上，機器擁有者始終能動底層資料。詳見 6.7 |