選型要回答兩個問題，而它們的交集決定機制：這個秘密會不會在每次呼叫裡送出去、以及撤銷一次要影響幾個呼叫方。兩題之前還有一個前提要先確認——選擇權在誰。對方的 API 文件寫什麼就是什麼的整合，與自己定介面的整合，能做的判斷完全不同。

本章涵蓋與不涵蓋

本章聚焦系統層那一把憑證的機制選擇。呼叫方身分該不該分層、分幾層在 7.29 API 認證的信任邊界分層——那是本章的上游，機制選型只在確定系統層要有獨立身分之後才發生。選定之後憑證怎麼核發與交付在 7.32 機器憑證的配發，上線後的輪替與回收在 7.6 秘密管理與機器憑證治理。各機制的實作細節（雙密過渡怎麼做、mTLS 的 nginx 設定、簽章素材怎麼對齊）在對應的實作文章，本章給的是選哪一個與為什麼。

本章 threat scope

In-scope：秘密隨請求送出而落在日誌與中繼 / 撤銷粒度與呼叫方數量不匹配 / 機制要求的基礎建設沒有跟上 / 換發憑證的那一跳成為單點。

Out-of-scope（路由到他章）：

• 呼叫方身分要分幾層 → 7.29
• 選定之後憑證怎麼交到對方手上 → 7.32
• 上線後的輪替、回收與事件收斂 → 7.6
• 這個機制屬於哪一類密碼學原語、金鑰放哪裡 → 7.28
• 憑證的信任鏈與續期節奏 → 7.5
• 一個系統代表某個特定的人 → 7.33

out-of-scope 的議題直接跳到對應章節。

從本章到實作

本章是 routing layer，沿兩條 chain 進入 implementation：

• Mechanism：問題節點表「前置控制面」欄的連結進知識卡，看該控制的機制、邊界與適用條件。
• Delivery：「交接路由」欄位指向 04 可觀測性、05 部署平台、06 可靠性、08 事故處理。本章有一列走 04，因為「秘密落進紀錄」的偵測與遮罩落在那一層。

兩條 chain 完成判準與模組級 chain 規格見 從章節到實作的 chain。

先確認自己有沒有選擇權

判別式是誰寫整合規格，不是誰是伺服器那一端。這兩者常常一致而不總是一致：接第三方的 webhook 時被呼叫的是自己的 API，而機制由對方的文件決定；提供平台給大量客戶接的一方即使一直在被呼叫，規格也是自己寫的。判錯這一題會讓後面兩問白做。

規格由對方寫時，能用的機制由對方提供。規格由自己寫時選擇權在自己，但每一個既有的呼叫方都要跟著改。既有介面換機制的邊界，是能不能同時接受新舊兩種機制並訂出落日期。 呼叫方兩百個一樣換得掉，只是要一年；做不到就只剩一次性切換，而那需要全體同時配合——這一支本站尚無專章，最小做法是把它當成一次對外的破壞性變更來排：先公告期限、期間新舊都收、到期日之後才關掉舊的，通用紀律見 11.6 向後相容的變更紀律。

沒有選擇權時本章其餘各節仍然有用，但用途不同：它給的是「照對方的方式接上去之後，我這邊還缺哪一塊」。對方只給一把長期 API key 時，暴露面與撤銷粒度都由那個選擇決定，自己能做的是在自己這一側補上日誌遮罩與存取隔離，並把差額記成已知風險。對方要求用它自己的 SDK 時連這一步都做不到——機制被封裝、看不見也遮罩不了，能留下的只有「這條整合的暴露面由對方的實作決定」這句紀錄，以及把它排進定期重評估。

雙向整合的兩個方向各跑一次。 我打對方用一把、對方回呼我用另一把，這是接第三方服務的標準形態，而兩個方向的規格作者、暴露面與撤銷路徑各自獨立。下方的判讀流程與四格表都是單向的，兩個方向要各走一遍、得到兩組答案。

兩個問題把選項分開

先分開兩個詞：憑證是這條整合的身分整體，秘密是其中不能外流的那一部分——共享密鑰的密鑰本身、mTLS 的私鑰。撤銷處理的是憑證，送不送出去說的是秘密。（7.6 的類型分層用的是另一套切法，那裡的「部署憑證」是與 secret、token、key 並列的四類之一。）

問題一：這個秘密本身要不要在每次呼叫裡送出去。 這一題決定它最後會留在哪些地方。

送出去的機制（共享密鑰、API key、client credentials 換 token 的那一次）把秘密交給整條傳輸路徑上的每一跳處理，而那些跳點各自有自己的記錄行為——反向代理的存取日誌、內容傳遞網路的邊緣節點、應用層的請求追蹤、以及對方那一側的同一組系統。秘密沒有洩漏，只是被記錄了，而記錄的保存期限與可讀範圍由那些系統各自的設定決定。放進網址參數是這一格最嚴重的形態，因為多數伺服器的預設存取日誌格式會完整記錄請求行、含查詢字串；放進 header 好一些，但請求追蹤與錯誤回報工具可能會抓 header——這一項各家預設不同，要逐一翻設定。兩者都查得到：翻一次自己的日誌格式設定與追蹤工具的欄位設定就知道。

不送出去的機制（共享密鑰簽章、mTLS）只把秘密用來運算：網路上流的是簽章值或握手結果，秘密本身留在兩端的記憶體裡。代價是兩邊都要實作運算邏輯，而排錯比「比對一個字串」難得多——失敗時只會得到「對不起來」，看不出是哪一個欄位不一致。

下方表格用「送得起」指這一題的判定結果：那些跳點的紀錄保存期限與可讀範圍查得出來、而且查出來的答案可以接受。查不出來就當作送不起。

跳點全在自己掌控之內、日誌設定翻得到而且沒問題時，這一題五秒鐘就答完，決策整個落在第二題與基礎建設那一欄。純內網的服務之間互相呼叫多半是這種情形。

問題二：撤銷一把憑證要影響幾個呼叫方。 這一題決定事件當天的處置範圍。

共享密鑰是一把服務全部，撤銷等於中斷整條整合，這條約束的實際份量見 7.29 身分維度分層模型 —— 該節中段列出系統層的撤銷由哪些事件觸發、以及為什麼同一個「立刻撤銷」的需求在這一層要用天或週計算。API key 與 mTLS 憑證是一個呼叫方一把，撤銷影響單一對象——而 API key 的這個能力來自那張登記表，不是來自憑證本身。粒度細到什麼程度是設計選擇，不是機制給定的：共享密鑰也可以每個對象發一把，代價是要維護那張表，而那正是 API key 這個名字實際指的東西。

兩題交叉之後的落點

兩個問題各自有兩個答案，交叉出四格，每一格有對應的機制：

右下那一格是實際上最常見的組合（同時接多個外部推送提供方、又不想讓密鑰進入日誌），而它的兩個選項成本差距在配套而非在密鑰數量：每方一把簽章密鑰要的是與 API key 同一張登記表，mTLS 要的是一整套憑證的簽發、續期與撤銷。前者是一張表、成本隨整合數變動，後者是一套基礎建設、多半是固定成本。所以整合數少時 mTLS 貴、共用同一個 CA 的整合夠多時成本結構會翻轉，攤提軸的算法見 7.32 的信任錨交叉點。

下表展開這些機制各自的性質。四格與下表的列不是一對一——共享密鑰簽章那一列同時承擔左下與右下兩格，差別在一把共用還是每方一把；右下那一格的另一個選項才是 mTLS。

真正決定撤銷粒度的不是機制的名字，是有沒有一張把憑證對應到呼叫方的表。 共享密鑰與 API key 在密碼學上是同一件事——都是持有即通過、都做等值比對——差別只在那張表。有表，撤一把只影響一個；沒有，撤一把影響全部。名字本身靠不住：有服務把全帳號共用的靜態 token 叫 API key、也有服務按夥伴發放並登記卻叫它 shared secret。所以「我們改用 API key」這句話在團隊裡要講清楚實質內容是建那張表，否則會被聽成改個 header 名字。

這張表也可以不由自己維護：雲平台派發的身分（實例掛載的角色、容器編排的服務帳號）粒度同樣是單一，而對應關係在平台那一側，自己這邊看得到卻改不了。這條路徑不在上表裡，它的判讀走 7.10 Workload Identity 與聯邦信任邊界，而它能不能用是 7.32 的第一題。

mTLS 的兩個補述

保護到哪裡結束。 mTLS 與簽章的私鑰或密鑰都留在本地（TLS 用私鑰簽握手訊息、HMAC 用密鑰算驗證值），但兩者保護到的位置不同：mTLS 的客戶端身分在 TLS 終止的那一點就結束，前面有負載平衡器或內容傳遞網路終止 TLS 時，身分要由終止點轉成 header 往後傳，於是問題變成「後端憑什麼信任那個 header」。簽章值則一路走到應用層，中途每一跳都改不了它。有終止點的架構要把這一跳的信任邊界一起設計，見 7.29 系統憑證下放客戶端。

撤了之後多久真的擋得住。 這與撤銷粒度是兩個問題：粒度是單一呼叫方，而生效時間由驗證側的檢查方式決定——撤銷清單有快取與更新間隔，線上查詢在查不到時多數實作預設放行。把延遲壓到有界的做法是縮短憑證有效期，而那要求續期是自動的，回到最右欄那一格。

OAuth client credentials 是另一個層次

它是取得憑證的流程，不是第五種機制，而流程裡用哪一種方式向授權伺服器證明自己，才決定秘密送不送出去。用 client secret 時秘密要送、而且是每次換 token 都送一次：RFC 6749 §4.4.2 要求每次 token 請求都做 client 認證，§4.4.3 又說不該發 refresh token，所以 token 過期只能再送一次 secret 去換——暴露頻率因此等於實例數乘上一天的秒數再除以 token 有效期：token 一小時的單一實例一天走 24 趟，而水平擴展的每個實例各自換各自的，五十個實例就是一千兩百趟——規模放大的正是暴露量。

同一個流程換成用私鑰簽出來的斷言（RFC 7523）或 mTLS 做 client 認證（RFC 8705）時，秘密就不送出去了，這一格移到四格表的下半。標準本身留了這個空間：RFC 6749 §2.3 明寫授權伺服器可以接受任何滿足其安全需求的 client 認證方式。

它真正帶來的是另一項：長期憑證與每次呼叫實際使用的憑證被分開，於是可以對後者設短有效期與細範圍，範圍表達見 authorization scope。已換出的 token 要等它過期還是撤得掉，取決於發行方有沒有提供撤銷端點與驗證方有沒有回查——無狀態驗證且不回查時才是「只能等它過期」。代價是換發端點成為每次呼叫的前置依賴。

判讀流程

1. 先問這條整合需不需要有一把要交出去的憑證。呼叫方能用執行環境本身證明身分時整套選型都不必進行，判讀走 7.32 的第一題 與 7.10。這一題答是的機率隨平台能力上升，而它一旦成立，下面四步全部作廢。
2. 再確認規格由誰寫。由對方寫時直接跳到最後的登記那一步。
3. 再問這個秘密送不送得起：傳輸路徑上有幾跳會記錄請求、那些記錄的保存期限與可讀範圍是什麼。確認不了時預設它會被記錄，選不送出去的那一類。
4. 接著數呼叫方。只有一個且短期內不會變時可以接受共用一把，並把「出現第二個呼叫方」寫成重新評估的觸發條件；兩個以上直接要一方一把的粒度。把這一題的答案與「秘密送不送得起」那一題交叉，落點見上方的四格表。
5. 再確認選中的機制要的基礎建設現在就有。mTLS 要問憑證續期是不是自動的、換發流程要問 token 端點掛掉時呼叫方怎麼辦。沒有的話這一項的建置要與整合本身一起排，而不是排在它之後；排不進去時只剩兩條路——退回同一格裡成本較低的那個選項（右下那格退回每方一把簽章密鑰），或接受並記錄例外，例外的期限與重評估條件見下方風險邊界裡「對方只提供一種機制」那一條。
6. 最後把選定的機制與上面各題的答案一起登記。自己核發憑證的接到 7.32 機器憑證的配發 的核發與交付，登記落在那一章定義的那份清單上。落點是 7.32 定義的那份清單，本章在那份清單上加一個欄位（機制）與一種列型態：沒有選擇權、也沒有自己發出憑證的整合同樣佔一列，機制欄寫「由對方決定」，另記差額風險與重評估觸發器。

問題節點（案例觸發式）

問題節點出現在什麼樣的系統

上表的訊號要等機制上線才量得到。設計階段對照的是下面這幾種形態。

秘密隨請求落進紀錄出現在把它當成一般參數處理的整合。網址參數這一種有兩種來源、處置不同：自己這邊「先讓它通」的除錯殘留改得掉，而對方的 API 只收查詢字串、或對方的 webhook 主控台設不了 header 這一種改不掉，只剩在自己這一側遮罩日誌並記成已知風險；header 那一種則是被工具帶進來的——請求追蹤與錯誤回報服務的預設多半抓完整 header，而那個預設在導入時沒有人逐項看過。識別動作是拿一段時間的存取紀錄搜尋自己的憑證前綴。

撤銷粒度與呼叫方不匹配出現在憑證比呼叫方先存在的系統。第一條整合開了一把密鑰，第二條來的時候那把已經能用，於是沿用——這與 7.6 token 分域不足 是同一個機制在機制選型層的形態。識別特徵是問得出「這把憑證現在有誰在用」的人只有一位。

基礎建設沒有跟上出現在安全評審把機制選對、而維運能力沒有一起評估的組織。選 mTLS 的決定在設計階段做，憑證續期的痛在一年後才發生，兩者中間隔著一次交接。它還有一半不在自己這一側：續期要對方同時換，所以就算自己這邊自動化做好了，中斷時間仍由對方的排期決定。

換發那一跳成為單點出現在剛從長期憑證換到動態換發的系統。換過去的動機是壓縮暴露窗口，而那個動機不會帶出「這個端點掛掉會怎樣」這個問題。最小做法有三項、都在呼叫方那一側：把換到的憑證快取到接近過期而不是每次呼叫都換、在過期前留一段提前續期的窗口讓失敗有第二次機會、以及換發失敗時明確決定要擋下請求還是沿用尚未過期的那一張。三項合起來把換發端點從「每次呼叫的前置」降成「每個週期的前置」，降級策略的形態見 fallback，那一跳本身的可用性目標走 06 可靠性。

基礎建設沒有跟上是這張表裡唯一在選型當下不留任何痕跡的一格。合規要求對外整合走 mTLS，團隊建了一個內部 CA、為當時的兩個對接方各簽了一張一年期憑證，上線順利。一年後兩張憑證在同一週到期，兩條整合同時斷，而那一週沒有任何人在等這件事發生。

沒有被提前發現，是因為憑證到期不產生漸進訊號：到期前一秒的連線與平常完全相同，監控盯的連線成功率在到期當下垂直落下、沒有前兆。「還剩多久到期」要主動去查才有，而查它的動作在自動續期尚未建立的環境裡沒有承載者——它不屬於任何一個既有的排程。

止血要重新簽發並在兩端同時換，而對方那一側要人工配合，於是中斷時間由對方的排期決定。真正的修法在選型當下：把續期自動化當成選 mTLS 的前置條件而非後續工作，路徑見 acme-automation 與 7.5 傳輸信任與憑證生命週期。

常見風險邊界

• 秘密出現在網址參數時，代表它的可讀範圍已經無法界定——各跳點的紀錄保存期限不由自己決定，處置要連同輪替一起做，輪替本身的節奏走 7.6 秘密管理與機器憑證治理。
• 同一把憑證服務兩個以上的呼叫方，而其中任一個是外部組織時，撤銷粒度的缺口會在事件當天變成「要中斷幾條整合」這個沒有好答案的問題。
• 選定的機制要求的基礎建設由人工承擔時，這條整合的可用性上限由那個人的排程決定，這超出工程修復能承擔的範圍。
• 換發端點沒有獨立的可用性目標時，代表所有依賴它的整合共用一個沒有人負責的單點。
• 對方只提供一種機制而那一種不符合自己的合規要求時，處置要往合約層或架構層走：要求對方支援、在中間加一層自己控制的代理、或接受並記錄例外，例外的期限與重評估條件見 7.14 資安治理例外與 Tripwire。

案例觸發參考

• 硬編碼憑證被檢索重用： USAHERDS 2021
• 憑證集中與輪替排序壓力： CircleCI 2023
• 第三方 token 成為內部入口： GitHub OAuth 2022
• 輪替的作用域與證據欄位示範： 7.27 Credential Rotation with Scoped Evidence

下一步路由

• 上游（要不要有獨立的系統層身分）：7.29 API 認證的信任邊界分層
• 選定之後憑證怎麼核發、交付與登記：7.32 機器憑證的配發
• 選了共享密鑰簽章之後的素材對齊與重放收斂：7.35 簽章對接的驗證收斂
• 這個機制屬於哪一類原語、金鑰放在哪一格：7.28 密碼學原語選型
• mTLS 的憑證生命週期判讀：7.5 傳輸信任與憑證生命週期
• 持有者是人而非系統時判讀軸換成載體（passkey、安全金鑰、智慧卡）：7.39 使用者持有型憑證
• 人類那一側的憑證怎麼帶進每個請求：7.36 憑證在請求中怎麼帶
• 上線後的輪替、回收與事件收斂：7.6 秘密管理與機器憑證治理
• 各機制的實作細節（雙密過渡、mTLS 部署、簽章實作）：API 認證的三層信任邊界 的「Layer 2：系統層」一節與它列出的各篇
• 例外的期限與重評估：7.14 資安治理例外與 Tripwire

這一章要交出去的是三樣東西：一份雙方確認過的驗證素材規格、一個換算得出上下界的窗口長度、以及一組分得開的拒絕原因。第一樣決定對接要花多久，第二樣決定驗簽通過之後還擋不擋得住重送，第三樣決定事件當天查得出方向。另有一項不必等對方就能修完：比對驗證值那一行用對函式。

本章涵蓋與不涵蓋

本章的三個收斂條件涵蓋範圍不同：驗證素材的對齊是共享密鑰簽章專屬，而重放窗口對任何接收外部推送的端點都成立（與用哪一種機制無關），比對方式對任何做等值比對的秘密都成立（API key 的比對有一模一樣的時間洩漏）。機制本身還沒選的讀者從 7.34 機器憑證的機制選型 進來；這個機制屬於哪一類原語、密鑰放在哪一格見 7.28 密碼學原語選型；密鑰的保存與輪替屬治理層，見 7.6 秘密管理與機器憑證治理。本章聚焦選定之後的收斂條件，機制本身的原理在 Message Authentication。下方反覆出現的驗證素材指的是進入計算的那串內容——哪些欄位、以什麼順序、用什麼編碼串接起來。

本章 threat scope

In-scope：驗證素材的定義兩端不一致 / 重放窗口未收斂 / 驗證值的比對方式抵銷機制強度。

Out-of-scope（路由到他章）：

• 該不該用共享密鑰簽章、與其他機制的取捨 → 7.34
• 密鑰放在哪一格、被誰拿得到 → 7.28
• 密鑰的保存與輪替節奏 → 7.6
• 素材規格變更時的相容判斷（本章不談版本策略，只到「規格要雙方共同確認」為止）→ 11.6 向後相容的變更紀律 的抽象層紀律

out-of-scope 的議題直接跳到對應章節。

從本章到實作

本章是 routing layer，沿兩條 chain 進入 implementation：

• Mechanism：問題節點表「前置控制面」欄的連結進知識卡，看該控制的機制、邊界與適用條件。
• Delivery：「交接路由」欄位指向 04 可觀測性、05 部署平台、06 可靠性、08 事故處理。重放窗口那一列走 04，因為拒絕原因分不分得開是監控設計的問題。

兩條 chain 完成判準與模組級 chain 規格見 從章節到實作的 chain。

問題節點（案例觸發式）

判讀流程

1. 先判這個端點需不需要時間軸的保護：重送一次會不會產生第二次副作用。不會的純查詢端點到這裡就結束，剩下兩項仍然要做。
2. 需要的話定窗口長度。第一題是對方的時間戳在事件產生時簽還是每次送出時簽，它決定下界怎麼算；換算與上下界交叉時的處置見下方「重放窗口的收斂條件」。
3. 接著確認素材規格是雙方共同確認過的一份，而不是各自一份文件。缺的話在第一次對接時補。自助式的供應商沒有那個對話（註冊完就上線、沒有窗口可談），這時退到單方規格：把實際收到的請求原樣存下幾筆當成規格的依據、據此寫回歸測試，並在文件裡標明依據是實測而非對方的文件。這樣做的差別在對方改了東西時測試會紅，而不是等到驗簽開始失敗才發現。
4. 再查程式碼裡比對驗證值那一行用的是不是等時比較函式。
5. 最後把窗口長度、素材規格、拒絕原因的分類與第 4 步的檢查結果寫下來。第 1 步判定為不需要時同樣要寫，記的是判定依據（這個端點重送不產生第二次副作用）——否則判定過而判定不需要，與根本沒判過，在產物上看起來一樣。自己是推送方時這幾項屬於對外契約的內容；自己是接收方時對外契約在對方手上，這幾項落在自己的整合紀錄與監控設定裡。兩種情形共同的最低要求是拒絕原因分得開，事件當下才查得出方向。

驗證素材的對齊成本

素材定義不一致是簽章對接裡反覆發生的耗時來源，特徵是失敗訊號不具指向性：驗證值對不起來時只會得到一個布林值，看不出是欄位少了一個、順序反了、還是時間戳的單位是秒而對方送的是毫秒。

這個特徵決定了它的成本結構：耗時不隨團隊能力下降，而是隨介面調整次數重複發生。每一次新增欄位、改變編碼、調整空值處理，兩端都要重新對齊一次，而每一次對齊都要付同樣的排錯成本。因此把素材規格寫進雙方共同的書面契約，這筆投資在整合的生命週期裡會被攤提多次——而寫進去的時機在第一次對接時成本最低，那時兩邊的人都還在同一個對話裡。

規格要涵蓋的項目、可在本機單方完成的診斷手法（先讓兩端各自對同一份輸入算一次，比對中間值而非最終值）與對接的檢查順序見 HMAC 簽章對接。

驗證素材定義不一致要有兩個團隊各自實作才會發生，因此它的密度與對接對象數量成正比。跨組織整合、集團內跨產品線、以及自己的服務對接第三方的 webhook 都落在這裡。識別特徵是雙方各有一份描述簽章怎麼算的文件，而沒有一份是雙方共同確認過的。

重放窗口的收斂條件

哪些端點需要這一步，判準是重送一次會不會產生第二次副作用：轉帳、下單、發送通知、狀態轉移都會，純查詢端點不會。接收外部 webhook 的端點風險最高——請求來自自己控制範圍之外，攻擊者可能就在傳輸路徑上，而 webhook 的重試機制本身就會產生大量重複請求，讓惡意重放藏在正常重試裡。

時間軸條件（驗證值涵蓋時間戳、接收端檢查新鮮度）擋住窗口外的重送，窗口內的重複由識別值去重承接，兩者的分工見 Replay Attack。這個節點的特殊之處在於缺的那一步從來沒有被排進工作項：驗簽做完了、測試綠了、上線了，而「還要比對時間戳與識別值」這件事沒有出現在任何一張清單上，所以它不是做失敗、是沒有人想到要做。

它的失敗長這樣：webhook 接收端照對方文件實作了簽章驗證，驗簽通過就代表這個請求出自對方，當下沒有人覺得還缺什麼——時間戳與識別值都在 payload 裡，兩者都沒有人比對。某次對方那端重試堆積之後，同一筆扣款被處理了好幾次。查起來每一筆都通過驗簽、每一筆的內容都合法，監控上是一串正常請求；而 webhook 本來就會重試，重複請求與惡意重放在日誌裡沒有任何欄位分得開。

補救的順序由重複落在哪一側決定，而這個案例落在窗口內側：重試堆積發生在幾秒到幾分鐘之內，新鮮度檢查放行它是正確行為，擋得住它的是識別值去重。所以先建去重儲存，再補時間戳的新鮮度檢查把窗口外的重送一併擋掉——兩道控制的分工見上一段。已經發生的重複副作用要逐筆對帳回滾，那部分的工作量由這個缺口存在了多久決定。

窗口長度是對接階段就要定的參數，兩端都能換算成具體的量。下界由對方的時間戳在什麼時候簽決定：送出時簽的話每次重試各自帶新的時間戳，下界就是量測到的 時鐘偏移 上界加餘裕，落在秒到分鐘級；產生時簽的話整串重試共用同一個時間戳，下界要改取時鐘偏移上界與對方最大重試退避間隔的較大者，而後者通常大上幾個數量級——退避超過窗口的那些合法重試會被判成過期，日誌上與攻擊分不開。這一題要向對方確認，退避表查不到時當作產生時簽並取對方公告的重試總時長，指數退避 是它最常見的形狀。

上界由去重的儲存量反推：窗口內的已處理識別值都要留著，請求速率乘上窗口長度就是要保留的筆數。這個數字撐不住時要動的是儲存形態而非窗口——存識別值的雜湊而非原值、讓儲存自己按存活時間淘汰——因為把窗口縮到下界以下會開始拒絕合法的重試，那與攻擊在日誌上分不開。兩端交叉到怎麼調都撐不住時，剩下的路是接受窗口外的重複由業務層的冪等承接，收斂點見 Idempotency Key。涉及金流或不可逆動作的端點直接取下界，不必在區間裡挑。

重放窗口未收斂出現在接收外部推送的端點，尤其是那些照著對方文件實作驗簽就上線的整合。這一格的成因與其餘節點不同：它不是做錯，是做完之後少做一步，因此它的出現率與驗簽實作的正確性無關——寫得越乾淨的實作越容易停在這裡，因為驗簽那一段看起來已經完成了。識別特徵是 payload 裡帶著時間戳與識別值，而接收端的程式碼裡找不到比對它們的地方。

比對方式抵銷機制強度

重算出的值要用等時比較來比對。一般的字串相等運算在第一個不吻合的位元組就回傳，回應時間因此洩漏吻合前綴的長度，攻擊者可以逐位元組推出正確的驗證值，收斂點見 Timing Attack。

比對方式抵銷強度出現在自己動手實作驗簽的服務。用對方提供的 SDK 多半不會踩到，因為那一行藏在函式庫裡（多半而非一定——SDK 沒覆蓋到的框架仍要自己寫）；照文件自己寫的會踩到，因為文件多半只說明怎麼算出那個值、不說怎麼比對它。識別動作是查程式碼裡比對驗證值那一行。

各語言都有現成的等時比較函式（hash_equals、compare_digest、ConstantTimeCompare 這一類），判別方式是查程式碼裡比對驗證值那一行用的是不是那個函式。函式取用不到的環境還有第二條路：把收到的值與自己算出的值各再做一次 HMAC（用一把當場產生的隨機密鑰）之後比對，攻擊者無法預測比對的是什麼，時間差因此不再洩漏前綴長度。它與其餘節點的差別在它完全在自己這一側，不必與對方協調。

常見風險邊界

• 驗證素材沒有雙方共同的書面規格時，代表對接成本會在每次介面調整時重新發生，而那筆成本每次都由兩邊同時付。
• 端點會產生第二次副作用而時間戳與識別值都沒有被比對時，保護只剩「這個請求出自對方」，攔截到的請求可以無限重放。
• 窗口長度取得比量測到的時鐘偏移還短時，正常請求會在漂移時被拒，而那個拒絕在日誌裡與攻擊的表徵相同。
• 監控把「驗證失敗」併成一個計數時，事件當下無法從監控判斷該往哪個方向查。三者指向不同：驗證值不符指向規格或密鑰不一致、時間戳過期指向時鐘偏移、識別值重複則是三者裡唯一需要區分惡意與正常重試的一種——它的絕大多數來源是對方的重試，所以不能只看計數，要查得到來源位址與時間分布。
• 對方的文件與實際送出的內容不一致而對方不願修文件時，處置要往契約層走：把實測結果寫成雙方確認過的附件，並把自己這一側的實作依據記成「依實測而非依文件」。對方連附件都不給時這條整合帶著一個沒有書面依據的假設上線，期限與重評估條件走 7.14 資安治理例外與 Tripwire。

案例觸發參考

• 簽章方案在對外契約上的實際形態： Stripe webhook 投遞契約
• 硬編碼憑證與固定認證路徑： USAHERDS 2021

下一步路由

• 上游（該不該用共享密鑰簽章）：7.34 機器憑證的機制選型
• 機制原理與能力上限：Message Authentication
• 素材的逐項清單與診斷手法：HMAC 簽章對接
• 密鑰放在哪一格、被誰拿得到：7.28 密碼學原語選型
• 密鑰怎麼交到對方手上：7.32 機器憑證的配發
• 密鑰的輪替與回收節奏：7.6 秘密管理與機器憑證治理
• 去重儲存與識別值的設計：Idempotency Key
• 素材規格新增欄位時兩端怎麼同步：本站尚無專章；通用的相容紀律見 11.6 向後相容的變更紀律，在那之前的最小做法是把新欄位設成可選、兩端各自先支援「有或沒有都算對」一段時間，再切成必填

HMAC 承擔的責任

HMAC 證明兩件事：這個請求出自持有密鑰的人，而且內容從發出到接收沒有被改過。它把「身分」與「完整性」綁在同一個值上，接收方只要用同一把密鑰重算一次，比對結果就能同時驗證兩者。

HMAC 的作用範圍限於認證。產生的簽章公開可見，訊息本身也照常明文傳輸 —— 它提供的是認證而非保密。想讓內容不可讀，需要的是傳輸層加密或內容加密，那是另一組機制。

這個定位決定了排錯方向：簽章對不上時，問題落在「雙方對輸入的定義不一致」，而不是「加密解密失敗」。

演算法實際在做什麼

HMAC 的呼叫在多數語言只有幾行，底下卻有四個決策點，每一個都是兩端可能對不齊的地方：

1final key = utf8.encode(secret);
2final message = utf8.encode('$timestamp$payload');
3final digest = Hmac(sha256, key).convert(message);
4return digest.toString();

輸入是位元組序列

雜湊函式接受的是位元組，字串需要先決定編碼方式。utf8.encode 把這個決定寫死，讓兩端對「同樣的字對應哪些位元組」有共識。

字串串接同樣要精確。'$timestamp$payload' 產生的是連續字元，中間沒有分隔符：

1'1784878245' + '[]'  ->  '1784878245[]'  ->  12 個位元組

對應到 PHP 的 $timestamp . $payload 是同一件事。這裡常見的落差是引號 —— 後端 dump 出來的 "payload" => "[]" 是輸出格式加的引號，實際值只有 [ 和 ] 兩個字元。

密鑰經過內外兩層衍生

HMAC 的定義是巢狀的兩次雜湊：

1HMAC(K, m) = H( (K' XOR opad) || H( (K' XOR ipad) || m ) )

其中 K' 是密鑰補零到雜湊的區塊長度，超過長度的密鑰先雜湊過再用；ipad 是位元組 0x36 重複填滿一個區塊，opad 是 0x5c。區塊長度隨演算法而定，SHA-256 是 64 位元組，SHA-512 是 128 —— 換演算法時這個常數要跟著換，否則算出的值會與函式庫對不上。

手工實作可以驗證這個結構：

 1String hmacByHand(List<int> key, List<int> message) {
 2  const blockSize = 64;
 3
 4  final normalizedKey = key.length > blockSize
 5      ? sha256.convert(key).bytes
 6      : key;
 7  final paddedKey = Uint8List(blockSize)..setAll(0, normalizedKey);
 8
 9  final innerKey = paddedKey.map((byte) => byte ^ 0x36).toList();
10  final outerKey = paddedKey.map((byte) => byte ^ 0x5c).toList();
11
12  final innerDigest = sha256.convert([...innerKey, ...message]).bytes;
13  return sha256.convert([...outerKey, ...innerDigest]).toString();
14}

跑起來會跟函式庫的輸出逐字相同。

兩層結構擋掉長度延伸攻擊

直觀的做法是把密鑰接在訊息前面直接雜湊，兩者的輸出完全不同：

以 secret = 'k'、message = '1784878245[]' 為例：

1HMAC(secret, message)          -> d436a5cb070ecd04162da2186f7db52b2e365faeefa0492fb8cd176675823124
2sha256(secret + message)       -> c9ac394e856626f834054d4b9747f4e42183db1cf22a157e170fa268bc321d88

差異來自安全性而非風格。SHA-256 屬於 Merkle–Damgård 結構，這類雜湊有一個性質：知道 H(secret + m) 的值、m 的內容，以及 secret 的長度，就能在不知道 secret 本身的前提下，算出 H(secret + m + 補位 + 延伸內容) 的合法值；長度未知時逐一窮舉，候選數量通常不大。偽造出的訊息會夾帶原本的補位位元組、不是乾淨的尾端追加——這條攻擊在自己的格式下可不可行，看接收端會不會接受補位落在 payload 中間。外層再包一次雜湊切斷了這條路徑。

理解這點的實務價值在於：對方文件寫 hash_hmac 或 HMAC 時，就要用函式庫的 HMAC 實作。自行以 sha256(secret + message) 拼接算出的值不會與它吻合。

輸出是小寫十六進位

Digest 內部是 32 個位元組，toString() 轉成小寫十六進位共 64 個字元。PHP 的 hash_hmac() 預設輸出同樣格式，所以兩端天然對齊。改用 Base64 或大寫十六進位的系統也存在，對接時先確認對方的輸出格式。

這個固定長度可以寫進測試當作格式護欄：

1expect(headers['X-Signature'], matches(RegExp(r'^[0-9a-f]{64}$')));

兩端必須逐項對齊的輸入

簽章值只呈現吻合或不吻合，不指出差異落在哪一項；對接時把輸入拆成獨立項目逐一確認，比反覆重試有效率。逐項的對象是簽章素材——進入 HMAC 計算的那一串內容（有些文件稱「驗證素材」）。

時間戳單位：簽章會放行、時效檢查才擋

時間戳的特殊之處：單位錯了，簽章未必揭發它。接收方通常直接拿 header 的原字串進簽章素材——重新格式化會多引入一個要對齊的決策點；於是發送方送毫秒、接收方也用同一串字重算，簽章吻合。真正擋下請求的是另一道時效檢查：毫秒值被當秒解讀會落在數萬年後，任何有效期窗口都不會通過。（接收方若先把時間戳解析成整數、再依自己認定的單位重新格式化才進素材，簽章才會在這一項不吻合。）

所以「簽章算法正確但仍被拒絕」是可能的。排查時把「簽章比對」與「時效檢查」當成兩道獨立關卡，比籠統地懷疑「簽章有問題」更快收斂。

時效檢查本身的窗口該設多寬，取決於兩端的 時鐘偏移 而非單位換算，那是另一個獨立的參數。

判讀訊號：如果對方的錯誤堆疊在修正某一項之後換了位置（例如從第 26 行移到第 46 行），代表通過了前一道檢查、撞上下一道。錯誤位置改變是進度的證據。

空請求的 payload

沒有 request body 的端點，簽章素材裡的 payload 段落取決於接收方怎麼取值：

• 讀原始 body（$request->getContent()）：空請求得到空字串
• 讀解析後的參數再序列化（json_encode($request->all())）：空請求得到 []

兩者在文件上都可能被寫成「payload」。想同時滿足兩種實作，可以讓 request body 就是簽章素材本身 —— 送出的位元組與簽名的位元組是同一份，接收方無論用哪種取法都會得到相同結果。

用簽章反推輸入

HMAC 是確定性的：同樣的密鑰與訊息永遠產生同樣的輸出。這個性質可以反過來用 —— 手上有對方收到的簽章與時間戳，加上自己的密鑰，就能反解出「送出去的那一刻，實際用的是哪組輸入」。

完整可執行的腳本如下。放進一個空目錄，pubspec.yaml 只需要 crypto 一個依賴，密鑰放同目錄的 .env.local（內容一行 API_SECRET=實際密鑰）：

 1// verify_signature.dart
 2import 'dart:convert';
 3import 'dart:io';
 4
 5import 'package:crypto/crypto.dart';
 6
 7String sign(String secret, String timestamp, String payload) {
 8  final key = utf8.encode(secret);
 9  final message = utf8.encode('$timestamp$payload');
10  return Hmac(sha256, key).convert(message).toString();
11}
12
13String readSecret(String path) {
14  final line = File(path)
15      .readAsLinesSync()
16      .firstWhere((line) => line.startsWith('API_SECRET='));
17  return line.split('=').sublist(1).join('=').trim();
18}
19
20void main(List<String> args) {
21  final sentTimestamp = args[0];
22  final sentSignature = args[1];
23  final secret = readSecret('.env.local');
24
25  for (final payload in const ['[]', '', '{}', 'null']) {
26    final signature = sign(secret, sentTimestamp, payload);
27    print('payload = $payload\t相符: ${signature == sentSignature}');
28  }
29}

1dart pub add crypto
2dart run verify_signature.dart 1784878245 d436a5cb070ecd04162da2186f7db52b2e365faeefa0492fb8cd176675823124

有一組吻合，就同時證明了兩件事：payload 定義是那一個，而且本機實作與執行中的程式走同一條路徑。它證明不了第三件事——與外部規格相符：自己的兩端可以一致地錯，例如同時漏掉同一個欄位。那要靠對方的測試向量、或語言中立的參照值重現對方的簽章（檢查順序的第二步）。

沒有任何一組吻合，代表變因落在候選集合之外：真實的 payload 取值不在清單裡、素材組成多納入了欄位（路徑、method 或額外 header）、串接順序或分隔符不同，也可能是本機密鑰與執行中的程式不同。順序上先擴大 payload 與素材組成的候選，再懷疑密鑰 —— 密鑰不一致是四種成因裡最少見的一種。

這個手法在編譯期常數的情境特別有用。以 Dart 為例，String.fromEnvironment 的值在編譯時就被寫進產出物，改了設定檔之後若只做 hot reload，執行中的程式仍然帶著舊值 —— 這種狀態在裝置上完全看不出來，卻能被反推立刻辨識。

操作前提：驗證腳本從設定檔讀密鑰，不從命令列參數傳入。命令列參數會留在 shell 歷史與行程列表裡。

對接時的檢查順序

問題可能落在網路層、輸入定義或密鑰本身，由外而內排查能較快縮小範圍：

1. 請求真的到了預期的位置 —— 在送出前把最終組出來的 URL 整串印出來，不是印 path 常數；兩者的差異正是中介層改寫的落點。全域的路徑改寫（語系前綴之類）常會套用到不該套用的外部呼叫上。對方端有存取日誌時，拿他們記錄到的路徑與自己印出的字串逐字比對，一次就能定位。

2. 確認演算法與素材組成算得出預期的值 —— 對方提供測試向量時直接重現它。對方沒有提供時，用系統內建的 openssl 建立一個語言中立的參照值：

   1printf '1784878245[]' | openssl dgst -sha256 -hmac 'k'

   printf 不附加換行，這一點決定結果 —— echo 會多送一個 \n，算出完全不同的值。輸出的 d436a5cb... 拿來與自己程式的輸出比對，相符就證明實作沒問題，範圍收斂到素材定義。這條路徑不限語言，Node、Python、Go 的實作都能用同一個參照值校準。

3. 用實際送出的簽章反推輸入 —— 確認執行中的程式用的密鑰與 payload 定義符合預期。

4. 前三項都通過仍被拒絕 —— 範圍已收斂到接收方的設定，這時請對方提供四項資料：他們重算出的簽章值、重算所用的素材字串（標出分隔符位置）、他們收到的 timestamp 與 body 原文、以及拒絕的原因碼（簽章不符或時效過期）。這四項對應前文的四個決策點，拿到之後不需要再往返第二輪。

前三項都能在本機完成，不需要對方配合，也不需要反覆重新部署。

判讀與邊界

這篇適用的情境：串接使用 HMAC 簽章驗證的外部 API、簽章比對失敗且錯誤訊息不具體。

不在範圍內：密鑰的配發、儲存與輪替機制；簽章之外的授權判斷（呼叫方有沒有權限存取該資源）；HTTPS 傳輸層安全。這些是獨立的設計問題。為什麼這個場景選訊息驗證而不是加密、金鑰該放在哪一端，屬於它上一層的選型判斷，見 7.28 密碼學原語選型；在同一批機器憑證機制裡為什麼選它，見 7.34 機器憑證的機制選型。素材對齊之外的另一個收斂條件（時間戳與識別值要被檢查）與這一篇是同一階段的工作，判讀見 7.35 簽章對接的驗證收斂；機制本身的責任邊界見 Message Authentication。

自己也是接收方時（雙向對接的情況），比對簽章要用等時比較函式而不是一般的字串相等運算，理由與逐位元組短路造成的洩漏見 Timing Attack。

對接完成之後，有兩個檢查值得留成測試而不是留在記憶裡。密鑰為空時要輸出明確訊息，否則它會偽裝成後端問題，讓排查方向整個偏掉。時間戳單位要寫成斷言（送出值與現在時間的差距落在合理範圍內），只檢查欄位有值的斷言擋不住單位錯誤 —— 而單位錯誤正是這類對接最常復發的一項。