(課程影片與縮圖將由 Microsoft 內容團隊在合併後新增,符合第14/15課的模式。)
本課將涵蓋:
完成本課後,你將能:
想像你部署了一個為 Contoso Travel 服務的 AI 代理。代理讀取客戶請求,呼叫航班 API 尋找選項,並代表客戶訂座。上季度,該代理處理了 50,000 筆訂單。
今日一位稽核人員來訪。他們問一個簡單問題:「請給我看你的代理做了什麼。」
你交出日誌檔案。稽核人員再提更難問題:「我怎麼知道這些日誌沒有被編輯過?」
這就是審計軌跡問題。如今多數代理部署依賴:
這些方法都無法在不要求稽核方信任某人(你、雲端供應商或資料庫廠商)的情況下回答問題。內部使用時此種信任往往可接受,但對於受規管的工作負載(金融、醫療保健、任何受歐盟 AI 法規約束的)則不然。
密碼學收據透過使簽署的聲明能夠獨立地 可驗證。稽核者仍然需要一個帶外的理由來信任簽署金鑰及 產生該聲明的組件。內嵌的金鑰證明自我一致性, 而非發行者身份或執行位置。
收據是一個 JSON 物件,記錄代理做了什麼,並附有數位簽名。
flowchart LR
A[Agent invokes a tool] --> B[Build receipt payload]
B --> C[Canonicalize JSON RFC 8785]
C --> E[Ed25519 sign canonical bytes]
E --> F[Receipt with signature]
F --> G[Auditor verifies offline]
G --> H{Signature valid?}
H -- yes --> I[Signed statement is intact]
H -- no --> J[Receipt rejected]
一份最簡收據長這樣:
{
"type": "agent.tool_call.v1",
"agent_id": "contoso-travel-bot",
"tool_name": "lookup_flights",
"tool_args_hash": "sha256:a3f9c1...",
"result_hash": "sha256:7b2e1d...",
"policy_id": "contoso-travel-policy-v3",
"timestamp": "2026-04-25T14:30:00Z",
"sequence": 47,
"previous_receipt_hash": "sha256:9d4e6a...",
"signature": {
"alg": "EdDSA",
"sig": "c5af83...",
"public_key": "8f3b2c..."
}
}
有三個屬性能發揮作用:
簽名. 收據由代理的閘道使用 Ed25519 私鑰簽署。 任何持有對應公鑰的人都可以離線驗證該簽名。 依賴方必須固定該金鑰或從收據外的受信任註冊庫解析它。 篡改任何已簽署欄位會使簽名失效。
標準化編碼。簽署前,收據會使用 JSON 標準化方案(JCS,RFC 8785)序列化。這確保兩套實作只要輸出相同邏輯收據,就會產生完全相同的位元組序列。若無標準化編碼,不同 JSON 序列化器會為相同內容產生不同簽名。
雜湊鏈。該 previous_receipt_hash 欄位將每個收據連結到前一個收據。移除或重新排序收據會破壞所呈現的序列。偵測截斷或由簽署者控制的重寫也需要一個已釘選的當前鏈頭、獨立見證的檢查點,或經過驗證的封閉族群承諾。
這些屬性共同帶來三項保證:
你不需要特殊函式庫即可產生收據。加密基元廣泛可用,邏輯只有幾十行 Python 程式碼。
位於 code_samples/18-signed-receipts.ipynb 的實作練習會逐步示範整個流程。受版本控制的 code_samples/18-signed-receipts.execution-receipt.json 會記錄最新一次乾淨執行的精確筆記本雜湊、Python 環境、儲存格數量和檢查,而不會更改課程已儲存的輸出。摘要版本:
import json
import hashlib
import base64
from nacl import signing
from jcs import canonicalize # RFC 8785 canonical JSON
def b64url_nopad(data: bytes) -> str:
return base64.urlsafe_b64encode(data).decode("ascii").rstrip("=")
def sha256_canonical(obj) -> str:
"""SHA-256 of a Python object's JCS-canonical JSON form."""
return f"sha256:{hashlib.sha256(canonicalize(obj)).hexdigest()}"
# Generate or load a signing key (in production, store in a key vault)
signing_key = signing.SigningKey.generate()
verify_key = signing_key.verify_key
TRUSTED_PUBLIC_KEYS = {b64url_nopad(bytes(verify_key))} # pinned out of band by the verifier
# Build the receipt payload (no signature yet)
tool_args = {"origin": "SYD", "destination": "LAX"}
tool_result = [{"flight": "QF11", "price": 1850, "stops": 0}]
payload = {
"type": "agent.tool_call.v1",
"agent_id": "contoso-travel-bot",
"tool_name": "lookup_flights",
"tool_args_hash": sha256_canonical(tool_args),
"result_hash": sha256_canonical(tool_result),
"policy_id": "contoso-travel-policy-v3",
"timestamp": "2026-04-25T14:30:00Z",
"sequence": 0,
"previous_receipt_hash": None,
}
# Canonicalize and sign the JCS bytes directly. PureEdDSA hashes internally.
canonical_bytes = canonicalize(payload)
signature_bytes = signing_key.sign(canonical_bytes).signature
# Attach a structured signature object.
receipt = {
**payload,
"signature": {
"alg": "EdDSA",
"sig": b64url_nopad(signature_bytes),
"public_key": b64url_nopad(bytes(verify_key)),
},
}
這就是整個簽署流程。筆記本中步驟會逐一引導。
驗證是相反操作:
import base64
import hashlib
from nacl import signing
from nacl.exceptions import CryptoError
from jcs import canonicalize
def b64url_decode(s: str) -> bytes:
padding = "=" * ((4 - len(s) % 4) % 4)
return base64.b64decode(s + padding, altchars=b"-_", validate=True)
def verify_receipt(receipt: dict, trusted_public_keys: set[str]) -> bool:
# The signature is a structured object: {"alg", "sig", "public_key"}.
if not isinstance(receipt, dict):
return False
sig_obj = receipt.get("signature")
if not isinstance(sig_obj, dict) or sig_obj.get("alg") != "EdDSA":
return False
try:
# An inline key proves only self-consistency. Trust is configured out of band.
public_key = sig_obj.get("public_key")
signature = sig_obj.get("sig")
if not isinstance(public_key, str) or not isinstance(signature, str):
return False
if public_key not in trusted_public_keys:
return False
payload = {k: v for k, v in receipt.items() if k != "signature"}
canonical_bytes = canonicalize(payload)
verify_key = signing.VerifyKey(b64url_decode(public_key))
verify_key.verify(canonical_bytes, b64url_decode(signature))
return True
except (CryptoError, TypeError, ValueError, KeyError, OverflowError):
return False
此函式接收一張收據以及信賴方已釘選的金鑰集合,並回傳
True 僅當簽名在被接受的金鑰下有效時。驗證不需要
網絡呼叫,但金鑰的信任仍然是外部配置的決定。
要觀察篡改偵測如何運作,筆記本示範:
tool_args_hash 欄位的一個位元組。這是收據防篡改性質的實務示範:任何改動,無論多小,都會破壞簽名。
單一簽署收據保護一個行為。串接收據鏈保護序列行為。
flowchart LR
R0[Receipt 0<br/>genesis] --> R1[Receipt 1]
R1 --> R2[Receipt 2]
R2 --> R3[Receipt 3]
R1 -. previous_receipt_hash .-> R0
R2 -. previous_receipt_hash .-> R1
R3 -. previous_receipt_hash .-> R2
每份收據記錄前一份收據的雜湊。要隱密刪除第2份收據,攻擊者必須:
previous_receipt_hash 欄位(會破壞第3份收據簽名),或者如果私鑰受到保護,且驗證者釘選一個經獨立見證的鏈 頭,這些攻擊是可被偵測的。將金鑰刊登在每個收據內並不足夠 充足:簽署者或攻擊者可以提出不同的金鑰、重寫一個後綴,或 截斷鏈,除非依賴方擁有外部信任和完整性錨點。
筆記本示範:
previous_receipt_hash 與前一收據的真實雜湊相符。這就是你如何產生一條審計追蹤,讓外部稽核員能在其 自己固定的簽發者金鑰與鏈檢查點下驗證,而無須信任你那個可變的日誌儲存庫。
這是本課最重要部分。收據很強大,但其能力有限。
收據證明三件事:
收據不證明:
policy_id 所指政策是否實際被評估,或若評估會否允許此行為。收據紀錄的是宣稱,而非實際執行。這個界線重要有兩原因:
常見誤解是認為「我們有收據」就代表「我們被治理」。事實不是。收據是基石。治理是你建立於基石之上的系統。
上述第 3 項值得成為獨立一節:一個操作憑證會寫「此金鑰簽署了此內容」,而不會寫「某個人授權了此事」。對於高風險操作(退款、刪除、電匯),由另一位核准者的簽名可以約束該具體操作。將該金鑰連結到一個人以及檢查該人是否在場仍然是獨立的職責。
後續的筆記本 code_samples/human-authorization-receipts.ipynb 新增了第二種收據類型,human.approval.v1,其封裝形狀與本課程的收據相同 (由 Ed25519 對其規範化的 JCS 位元組簽署的類型化載荷,且 signature 物件位於已簽署位元組之外). 批准者金鑰會簽署 完整的規範化動作及其摘要;代理者金鑰會簽署一份聲明,載有 相同的動作摘要 和 parent_approval_ref,批准的 receipt_hash,與你在上面建立的鏈中 previous_receipt_hash 的慣例相同。 一個 verify_chain 會在 分開釘選的金鑰註冊表 (核准者金鑰與代理人金鑰), 因此程式碼路徑是共用的但授權實體永遠不會共用。
這項帶來的性質,謹慎陳述:已鎖定的核准者金鑰簽署了這個精確的 動作,且代理金鑰後來簽署了一份載有相同動作摘要的聲明。 這是有用的證據,但單憑它並不能證明該動作已被執行。為了 控制執行,該確切的批准也必須在 實際執行者邊界;未知的提供者結果必須保持未知,而不是 被盲目重試。筆記本的拒絕夾具測試收據鏈層:
每一項拒絕都有不同的理由,因此審核者在讀到拒絕時可以判斷是授權已失效還是所聲稱的操作改變了。驗證是唯讀且可重複的:它不會消耗批准或呼叫提供者。獨立的執行器需要具備持久且原子化的重放保護,並明確區分成功、失敗與不確定的結果。人類批准收據是本課程定義的一種教學性組合,而不是 draft-farley-acta-signed-receipts 定義的收據類型。
本課 Python 程式碼刻意簡潔,你可以逐行理解運作。在生產環境,你有兩種選擇:
直接建構在加密基元上。 上述約 50 行程式碼已足夠多數用例。PyNaCl(Ed25519)和 jcs(標準化 JSON)皆為維護良好且經過審核的函式庫。
使用生產級收據函式庫。 多個開源專案實作相同模式並增添功能(金鑰輪替、批次驗證、JWK Set 分發、政策引擎整合):
draft-farley-acta-signed-receipts,第02版)定義的 JCS 和簽名範圍慣例。本課的扁平教育收據與草案中的 {payload, signature} 信封格式不同,且不宣稱為標準相容實作。該草案發佈了共通相容性測試集(agent-governance-testvectors),用於目標其網路格式的實作。protect-mcp(npm)與 @veritasacta/verify(npm)封裝 Node 環境的收據簽署與離線驗證功能,目標為封裝任一 MCP 伺服器以產生防篡改審計軌跡,包括持有共簽流程,其中暫停動作會產生綁定動作摘要的核准收據(桌面流程使用 WebAuthn 支援),與上文真人核准筆記本相同模式。pip install nobulex) 提供相同 Ed25519 + JCS 簽署模式,含 LangChain 與 CrewAI 整合,且公布交叉驗證測試向量以及通過 OWASP PR #2210 出版合規映射。
- EMILIA Protocol 提供一個互補的精確行為強制層:可離線驗證的核准收據、綁定的 WebAuthn 或法定人數授權、在執行者邊界的一次性消耗,以及一條明確的不確定結果路徑。其框架適配器將收據視為必要的證據,而非外部效果已發生的證明。自行開發與使用函式庫的抉擇,類似於開發自己 JWT 函式庫與使用經過測試的函式庫的決定:兩者合理;函式庫節省時間並降低審核範圍;自己開發則逼你徹底理解每個基元。本課教授自己開發路徑,提供任一選擇的基礎。
在開始實作練習前測試你的理解。
1. 收據是以代理的私鑰 Ed25519 簽署。稽核人只有公鑰。稽核人能離線驗證收據嗎?
2. 攻擊者修改收據的 policy_id 欄位,聲稱其受更寬鬆政策管轄。簽名是對原始載荷。驗證時會發生什麼?
3. 為何收據包括 tool_args_hash 和 result_hash,而不是原始參數和結果?
4. previous_receipt_hash 欄位將每張收據連接到前一張。如果攻擊者靜默刪除鏈中某張收據,什麼會變得無效?
5. 一張收據驗證成功。這證明代理的行動是正確、合理,或符合法規嗎?
打開 code_samples/18-signed-receipts.ipynb 並完成以下四個部分:
延伸挑戰 1: 擴展收據結構,添加你自己選擇的欄位(例如用於追蹤的請求 ID),更新正規化簽名邏輯以包含它,並確認收據仍可成功往返驗證。然後簽名後修改該欄位,確認驗證失敗。這強迫你理解正規化編碼的每一字節如何影響簽名。
延伸挑戰 2: 將兩張收據的正規化字節按確定性順序串接,進行 SHA-256 雜湊,並將產生的摘要作為第三張收據的一個新欄位嵌入,再簽名它。驗證三張收據仍可往返驗證。你剛建構了一種一步包含證明:持有第三張收據的任何人都能證明在簽名時前兩張收據存在,而無需公開它們內容。這是大規模可選擇披露收據(Merkle 承諾,RFC 6962)所使用的模式。
密碼學收據為 AI 代理提供了審計軌跡,特點包括:
它們不能取代輸入驗證、政策執行、執行者準入、結果證據、完整性控制或身份基礎設施。 它們是這些層的基礎。 在受規管或多組織的工作流程中,收據使特定的發行者聲明 可在稽核者自身的信任配置下獨立核查。
最重要的要點:收據證明某個特定的金鑰簽署了特定的 內容。隨附的時間戳記除非另有時間見證,否則是簽署者的主張。 一個 收據並不證明其內容為真、某個動作已被執行,或是 記錄集是完整的。務必嚴格區分這些差異。
當你準備從本課進階到實際環境部署簽署收據的代理時:
加入 Microsoft Foundry Discord 與其他學習者交流,參加辦公時間,獲得你的 AI 代理疑問解答。
本課涵蓋單張收據簽署與雜湊鏈式序列。這些原語可組成你治理態勢成熟後可能遇到的多種進階模式:
authorization_*)和執行後(result_*)兩部分,並各自獨立簽名,適合授權決策與觀察結果由不同行為者或不同時點產生。這可在本課程教的收據格式上加法組合。result_hash 的任何字節。現實中載荷常比單一工具調用結果更豐富:決策前推理(模型預測、考慮的選項、證據及其完整性、風險姿態、問責鏈、門檻結果)都可包含在載荷內,並由單張收據封裝。這保持收據格式簡潔,同時載荷架構可按領域演變。alg 標籤並不足以達成遷移:設定檔必須定義 ML-DSA 金鑰編碼、規範化已簽名位元組、驗證、依賴方政策、抗降級能力,以及遷移語義。在提出相容性主張之前,應針對共享向量規劃並測試雙重簽名遷移。免責聲明: 本文件使用 AI 翻譯服務 Co-op Translator 進行翻譯。雖然我們力求準確,但請注意,自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應被視為權威來源。對於重要資訊,建議尋求專業人工翻譯。我們不對因使用本翻譯而引起的任何誤解或曲解承擔責任。