Sledujte video lekce: Zabezpečení AI agentů pomocí kryptografických potvrzení
(Video lekce a náhled bude přidán týmem Microsoftu po sloučení, v souladu se vzorem lekcí 14 / 15.)
Tato lekce pokryje:
Po absolvování této lekce budete umět:
Představte si, že jste nasadili AI agenta pro Contoso Travel. Agent čte požadavky zákazníků, volá API leteckých společností pro vyhledávání možností a rezervuje místa za zákazníka. Minulý kvartál agent zpracoval 50 000 rezervací.
Dnes přijde auditor. Položí jednoduchou otázku: „Ukažte mi, co váš agent dělal.“
Předáte mu své logy. Auditor se podívá a položí těžší otázku: „Jak vím, že tyto logy nebyly upraveny?“
To je problém auditní stopy. Většina nasazení agentů dnes spoléhá na:
Žádný z nich nemůže odpovědět na auditorovu otázku, aniž by auditor musel někomu důvěřovat (vám, vašemu cloudovému poskytovateli, vašemu dodavateli databáze). Pro interní použití je tato důvěra často přijatelná. Pro regulované pracovní zátěže (finance, zdravotnictví, cokoliv podléhající EU AI Act) ne.
Kryptografická potvrzení tento problém řeší tím, že každou akci agenta lze ověřit nezávisle. Auditor vám nemusí důvěřovat. Potřebuje pouze váš veřejný klíč a samotné potvrzení.
Potvrzení je JSON objekt, který zaznamenává, co agent udělal, podepsaný digitálním podpisem.
flowchart LR
A[Agent vyvolá nástroj] --> B[Sestavit data účtenky]
B --> C[Kanonizovat JSON RFC 8785]
C --> E[Ed25519 podepsat kanonické bajty]
E --> F[Účtenka s podpisem]
F --> G[Auditor ověřuje offline]
G --> H{Platný podpis?}
H -- yes --> I[Důkaz odolný proti manipulaci]
H -- no --> J[Účtenka zamítnuta]
Minimalistické potvrzení vypadá takto:
{
"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..."
}
}
Tři vlastnosti provádějí práci:
Podpis. Potvrzení je podepsané branou agenta (gateway) pomocí soukromého klíče Ed25519. Každý, kdo má odpovídající veřejný klíč, může podpis ověřit offline. Úprava jakéhokoli pole podpis zneplatní.
Kanonické kódování. Před podpisem je potvrzení serializováno pomocí JSON Canonicalization Scheme (JCS, RFC 8785). To zajišťuje, že dvě implementace, které vytvoří stejný logický obsah, vytvoří bajtově totožný výstup. Bez kanonizace by různé JSON serializéry vytvářely odlišné podpisy pro stejný obsah.
Hashový řetězec. Pole previous_receipt_hash spojuje každé potvrzení s tím předchozím. Odstranění nebo přeskupení potvrzení rozbije každý následující řetězový článek. Manipulace se stává viditelnou na úrovni řetězce i když jsou jednotlivé podpisy obcházeny.
Společně tyto vlastnosti zajišťují tři garance:
K výrobě potvrzení nepotřebujete speciální knihovnu. Kryptografické primitiva jsou široce dostupná a logika zabere pár desítek řádků Pythonu.
Praktické cvičení v code_samples/18-signed-receipts.ipynb provádí celý proces. Stručná verze:
import json
import hashlib
import base64
from nacl import signing
from jcs import canonicalize # Canonical JSON podle RFC 8785
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()}"
# Vygenerujte nebo načtěte podpisový klíč (v produkci uložit do trezoru klíčů)
signing_key = signing.SigningKey.generate()
verify_key = signing_key.verify_key
# Sestavte obsah účtenky (zatím bez podpisu)
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,
}
# Kanonizujte a podepište bajty JCS přímo. PureEdDSA interně hashuje.
canonical_bytes = canonicalize(payload)
signature_bytes = signing_key.sign(canonical_bytes).signature
# Připojte strukturovaný objekt podpisu.
receipt = {
**payload,
"signature": {
"alg": "EdDSA",
"sig": b64url_nopad(signature_bytes),
"public_key": b64url_nopad(bytes(verify_key)),
},
}
To je celý podpisový pipeline. V notebooku jsou probrány všechny kroky.
Ověření je inverzní operace:
import base64
import hashlib
from nacl import signing
from nacl.exceptions import BadSignatureError
from jcs import canonicalize
def b64url_decode(s: str) -> bytes:
padding = "=" * ((4 - len(s) % 4) % 4)
return base64.urlsafe_b64decode(s + padding)
def verify_receipt(receipt: dict) -> bool:
# Podpis je strukturovaný objekt: {"alg", "sig", "public_key"}.
sig_obj = receipt.get("signature")
if not sig_obj or sig_obj.get("alg") != "EdDSA":
return False
# Zrekonstruujte obsah, který byl skutečně podepsán (vše kromě podpisu).
payload = {k: v for k, v in receipt.items() if k != "signature"}
canonical_bytes = canonicalize(payload)
try:
verify_key = signing.VerifyKey(b64url_decode(sig_obj["public_key"]))
verify_key.verify(canonical_bytes, b64url_decode(sig_obj["sig"]))
return True
except BadSignatureError:
return False
Tato funkce přijímá potvrzení a vrací True, pokud je podpis platný, jinak False. Žádné volání sítě, žádná závislost na službě, žádná důvěra v třetí stranu.
Pro předvedení detekce manipulace notebook ukazuje:
tool_args_hash.To je praktická ukázka, že potvrzení jsou evidentní vůči manipulaci: jakákoliv úprava, jakkoliv malá, zničí podpis.
Jedno podepsané potvrzení chrání jednu akci. Řetězec potvrzení chrání posloupnost.
flowchart LR
R0[Výpis 0<br/>genesis] --> R1[Výpis 1]
R1 --> R2[Výpis 2]
R2 --> R3[Výpis 3]
R1 -. previous_receipt_hash .-> R0
R2 -. previous_receipt_hash .-> R1
R3 -. previous_receipt_hash .-> R2
Každé potvrzení zaznamenává hash potvrzení předchozího. Pro tiché odstranění potvrzení 2 by útočník musel:
previous_receipt_hash potvrzení 3 (rozbije podpis potvrzení 3), NEBOPokud je soukromý klíč v hardwarovém úložišti a veřejný klíč zveřejníte s každým potvrzením, žádný z těchto útoků není možný bez odhalení.
Notebook ukazuje:
previous_receipt_hash každého potvrzení odpovídá skutečnému hashi předchozího potvrzení.Takto vytvoříte auditní stopu, kterou může externí auditor ověřit bez důvěry v vás.
Toto je nejdůležitější část této lekce. Potvrzení jsou silná, ale jejich síla je omezená.
Potvrzení dokazují tři věci:
Potvrzení nedokazují:
Správnost: že akce agenta byla správná akce. Potvrzení může být podepsáno i pro špatnou odpověď stejně jako pro správnou.
policy_id byla skutečně vyhodnocena, nebo že by toto jednání povolila, pokud by bylo zkontrolováno. Potvrzení zaznamenává, co bylo tvrzeno, ne co bylo vynuceno.Tato hranice je důležitá ze dvou důvodů:
Častou chybou je předpokládat, že „máme potvrzení“ znamená „jsme řízeni.“ Není tomu tak. Potvrzení jsou základ. Řízení je systém, který na něm vybudujete.
Bod 3 výše stojí za vlastní sekci: potvrzení akce říká „tento klíč podepsal tento obsah,“ nikdy ne „člověk to autorizoval.“ Pro akce s vysokým rizikem (vrácení peněz, mazání, bankovní převody) požadují rámce řízení právě tento chybějící výrok, který lze vyrobit pomocí stejných primitiv, která jste v této lekci již použili.
Následující poznámkový blok code_samples/human-authorization-receipts.ipynb přidává druhý typ potvrzení, human.approval.v1, ve stejném obalovém formátu jako potvrzení z této lekce (typovaný payload podepsaný Ed25519 přes jeho kanonické JCS bajty, s objektem signature mimo podepsané bajty). Pojmenovaný schvalovatel podepíše celou kanonickou akci a její digest před vykonáním; potvrzení akce agenta nese stejný digest akce a parent_approval_ref, tj. receipt_hash schválení, stejný konvenční způsob jako previous_receipt_hash v řetězci, který jste vybudovali výše. Jedno verify_chain ověřuje oba artefakty pod samostatnými registrovanými klíči (klíče schvalovatele vs klíče agenta), takže kódová cesta je sdílená, ale autority nikdy.
Vlastnost, kterou toto umožňuje, pečlivě vyjádřeno: člověk schválil právě tuto přesnou akci a agent přesně tuto schválenou akci vykonal. Testovací příklady v poznámkovém bloku dělají tuto vlastnost skutečnou, nikoli jen tvrzenou:
Každé selhání zamítne z důvodu, takže auditor, který čte zamítnutí, může poznat, zda autorita ztratila platnost nebo zda se změnila vykonaná akce. Pravidlo, které poznámkový blok učí: podepsané schválení samo o sobě není autorita. Autorita existuje pouze tehdy, když obě potvrzení stále vážou v okamžiku vykonání na stejnou kanonickou akci. Potvrzení schválení člověkem je vzdělávací kompozicí definovanou v této lekci, není typem potvrzení definovaným v draft-farley-acta-signed-receipts.
Python kód této lekce je záměrně jednoduchý, abyste mohli každý řádek přečíst a přesně pochopit, co se děje. V produkci máte dvě možnosti:
Stavět přímo na kryptografických primitivech. 50 řádků, které jste viděli výše, stačí pro mnoho případů použití. PyNaCl (Ed25519) a balíček jcs (kanonický JSON) jsou dobře udržované a auditované knihovny.
Použít produkční knihovnu potvrzení. Několik projektů s otevřeným zdrojovým kódem implementuje stejný vzor s dalšími funkcemi (rotace klíčů, hromadné ověřování, distribuce JWK sad, integrace s politikami):
draft-farley-acta-signed-receipts, revize 02). Vzdělávací lekce používá jednodušší potvrzení odlišné od obálky návrhu {payload, signature} a není prezentována jako konformní implementace. Návrh zveřejňuje sdílený soubor testovacích vektorů (agent-governance-testvectors) pro implementace cílené na jeho formát přenosu dat.protect-mcp (npm) a @veritasacta/verify (npm) poskytují Node.js implementaci podpisu potvrzení a offline ověřování, určené pro zabalení jakéhokoli MCP serveru do důkazu proti manipulaci auditním záznamem, včetně režimu drženého pro spolupodepisování, kdy pozastavená akce vydá schvalovací potvrzení vázané na digest akce (podporované WebAuthn v desktopovém režimu), stejný vzor schvalovacího potvrzení jako v poznámkovém bloku schvalování člověkem výše.pip install nobulex) poskytuje stejný vzor Ed25519 + JCS podepisování v Pythonu s integracemi LangChain a CrewAI, včetně zveřejněných testovacích vektorů pro křížovou validaci a mapování souladu přispěné prostřednictvím OWASP PR #2210.Rozhodnutí mezi vlastním řešením a použitím knihovny odpovídá rozhodnutí o vlastní nebo knihovní implementaci JWT: obojí je rozumné; knihovna šetří čas a snižuje auditní plochu; cesta od začátku vyžaduje pochopení každé primitivy. Tato lekce učí cestu od začátku, abyste měli základ pro obě možnosti.
Otestujte své porozumění před přechodem na cvičení.
1. Potvrzení je podepsáno privátním Ed25519 klíčem agenta. Auditor má pouze veřejný klíč. Může auditor offline ověřit potvrzení?
2. Útočník změní pole policy_id v potvrzení, aby tvrdil, že podléhalo benevolentnější politice. Podpis byl však nad původním payloadem. Co se stane při ověření?
3. Proč příjem obsahuje tool_args_hash a result_hash namísto surových argumentů a výsledku?
4. Pole previous_receipt_hash spojuje každý příjem s jeho předchůdcem. Pokud útočník potichu odstraní jeden příjem ze středu řetězce, co se stane neplatným?
5. Příjem je platně ověřen. Dokazuje to, že akce agenta byla správná, rozumná nebo v souladu s pravidly?
Otevřete code_samples/18-signed-receipts.ipynb a dokončete všechny čtyři části:
Náročnější úkol 1: rozšiřte schéma příjmu o další vámi vybrané pole (například ID požadavku pro trasování), aktualizujte kanonickou logiku podepisování tak, aby ho zahrnovala, a potvrďte, že příjem stále projde ověřením. Pak pole po podepsání změňte a potvrďte, že ověření selže. To vás nutí pochopit, jak každý bajt kanonického kódování přispívá k podpisu.
Náročnější úkol 2: SHA-256 požádejte dva své příjmy dohromady (spojte jejich kanonické bajty v deterministickém pořadí) a vložte výsledný digest jako nové pole do třetího příjmu před jeho podepsáním. Ověřte, že všechny tři příjmy stále projdou ověřením. Právě jste postavili jednorázový důkaz začlenění: kdokoli držící třetí příjem může dokázat, že první dva existovaly v době, kdy byl podepsán, aniž by bylo nutné odhalit jejich obsah. Toto je vzor, který selektivní-disclosure příjmy používají ve velkém měřítku (Merkleovy závazky, RFC 6962).
Kryptografické příjmy dávají AI agentům auditní stopu, která je:
Nejsou náhradou za validaci vstupů, prosazování politik nebo infrastrukturu identity. Jsou základem těchto vrstev. Když nasazujete agenty do regulovaných prostředí, vícestupňových pracovních toků nebo jakéhokoli nastavení, kde budoucí auditor nelze předpokládat jako důvěryhodný, příjmy jsou způsobem, jak zajistit poctivost auditní stopy.
Nejdůležitější poznatek: příjmy dokazují, kdo co kdy řekl. Nedokazují, že to, co bylo řečeno, bylo pravdivé nebo správné. Udržujte tuto distinkci pevně. Je to rozdíl mezi poctivým systémem původu a zavádějícím.
Až budete připraveni přejít z této lekce k nasazení agentů s podepisovanými příjmy v reálném prostředí:
https://your-org.example.com/.well-known/agent-keys.json.Připojte se k Microsoft Foundry Discord, kde potkáte další studenty, zúčastníte se konzultačních hodin a získáte odpovědi na své otázky o AI agentech.
Tato lekce pokrývá podepisování jednoho příjmu a řetězení pomocí hashů. Stejné primitivy tvoří základ několika pokročilejších vzorů, na které můžete narazit, jak vaše správa zrání:
authorization_*) a po vykonávací (result_*) poloviny s nezávislými podpisy, užitečné, když rozhodnutí o autorizaci a pozorovaný výsledek vytvářejí různí aktéři nebo v různých časech. Tyto vzory se aditivně skládají na formát příjmu vyučovaný v této lekci.result_hash. Reálné obsahy jsou často bohatší než jediný výsledek volání nástroje: předrozhodovací uvažování (predikce modelu, zvážené možnosti, důkazy a jejich úplnost, rizikový postoj, odpovědnost, výsledek kontroly) vše může žít uvnitř obsahu, který je uzavřen jedním příjmem. To udržuje formát příjmu minimální a zároveň umožňuje vývoj obsahových schémat podle domény.signature.alg může nést ML-DSA-65 (standard postkvantového podpisu NIST) kdykoli potřebujete migrovat. Plánujte přechodné období, kdy jsou příjmy podepisovány oběma způsoby.Prohlášení o omezení odpovědnosti: Tento dokument byl přeložen pomocí AI překladatelské služby Co-op Translator. Přestože usilujeme o co největší přesnost, mějte prosím na paměti, že automatizované překlady mohou obsahovat chyby nebo nepřesnosti. Originální dokument v jeho mateřském jazyce by měl být považován za autoritativní zdroj. Pro kritické informace se doporučuje profesionální lidský překlad. Nejsme odpovědní za jakékoli nedorozumění nebo nesprávné interpretace vzniklé použitím tohoto překladu.