Nézze meg az oktatóvideót: AI Ügynökök Biztosítása Kriptográfiai Bizonylatokkal
(Az oktatóvideót és a miniatűr képet a Microsoft tartalomcsapata fogja hozzáadni az egyesítés után, az 14/15. leckeminta alapján.)
Ez a lecke a következőket fogja ismertetni:
A lecke elvégzése után képes lesz:
Képzelje el, hogy telepített egy AI ügynököt a Contoso Travel számára. Az ügynök elolvassa az ügyfél kéréseit, lekérdezi a járatokat egy API-n keresztül, és lefoglalja a helyeket az ügyfél nevében. Az elmúlt negyedévben 50 000 foglalást dolgozott fel.
Ma megjelenik egy auditor. Egyszerű kérdést tesz fel: “Mutassa meg, mit csinált a ügynöke.”
Átadja a naplófájlokat. Az auditor megnézi őket, majd feltesz egy nehezebb kérdést: “Hogyan tudom, hogy ezeket a naplókat nem szerkesztették?”
Ez az auditnapló probléma. A legtöbb mai ügynök telepítés a következőkre támaszkodik:
Egyik sem tud válaszolni az auditor kérdésére anélkül, hogy az auditor valakiben megbízzon (Önben, a felhőszolgáltatóban, az adatbázis beszállítóban). Belső használatra ez gyakran elfogadható, szabályozott munkaterheléseknél (pénzügy, egészségügy, az EU AI törvény hatálya alatt) nem.
A kriptográfiai bizonylatok ezt a problémát szűkítik le azzal, hogy az aláírt állítást függetlenül ellenőrizhetővé teszik. Az auditor továbbra is kívülről kap megbízható okot az aláíró kulcs és az állítást előállító komponens meglétének elfogadására. Egy beágyazott kulcs önkonzisztenciát bizonyít, nem az kibocsátó személyazonosságát vagy a végrehajtás helyét.
Egy bizonylat egy JSON objektum, amely rögzíti, mit csinált az ügynök, digitális aláírással ellátva.
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]
Egy minimális bizonylat így néz ki:
{
"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..."
}
}
Három tulajdonság végzi a munkát:
Az aláírás. A bizonylatot az ügynök kapuja írja alá egy Ed25519 privát kulccsal. Bárki, akinek megvan a megfelelő nyilvános kulcs, offline ellenőrizheti az aláírást. Az ellenőrzőtársaságnak azt a kulcsot kell rögzítenie, vagy egy megbízható nyilvántartásból kell lekérnie a bizonylaton kívül. Bármely aláírt mező manipulálása érvényteleníti az aláírást.
Kanonikus kódolás. Az aláírás előtt a bizonylatot a JSON Kanonizációs Séma (JCS, RFC 8785) szerint szerializálják. Ez biztosítja, hogy két implementáció, amely ugyanazt a logikai bizonylatot állítja elő, bájtonként azonos kimenetet produkáljon. Kanonizáció nélkül különböző JSON szerializálók eltérő aláírásokat adnának ugyanarra a tartalomra.
Hash láncolás. A previous_receipt_hash mező összeköti az egyes bizonylatokat az előtte állóval. Egy bizonylat eltávolítása vagy átrendezése megszakítja a bemutatott láncot. A csonkolás vagy az aláíró által vezérelt átírás észlelése azt is megköveteli, hogy a jelenlegi láncfejet rögzítsék, függetlenül tanúsított ellenőrzőponttal vagy hitelesített zárt populációs kötelezettségvállalással.
Ezek a tulajdonságok együtt három garanciát nyújtanak:
Bizonylat készítéséhez nincs szükség speciális könyvtárra. A kriptográfiai primitívek széles körben elérhetőek, a logika néhány tucat Python sor.
A gyakorlati feladatok a code_samples/18-signed-receipts.ipynb alatt végigvezetik a teljes folyamatot. A forrásvezérelt code_samples/18-signed-receipts.execution-receipt.json rögzíti a pontos notebook hash-t, Python környezetet, cellaszámot és az ellenőrzéseket a legutóbbi tiszta futásból anélkül, hogy megváltoztatná a lecke mentett kimeneteit. Az összefoglaló változat:
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)),
},
}
Ez az egész aláírási folyamat. A notebook feladatok az egyes lépéseket részletesen bemutatják.
Az ellenőrzés a fordított művelet:
import base64
import hashlib
from nacl import signing
from nacl.exceptions import CryptoError
from jcs import canonicalize
def b64url_decode(s: str) -> bytes:
# Strict: Python's decoder skips characters outside the alphabet and also
# accepts padding, the standard +/ alphabet and non-zero spare bits.
# Re-encoding and comparing accepts only the one unpadded base64url form.
padding = "=" * ((4 - len(s) % 4) % 4)
data = base64.urlsafe_b64decode(s + padding)
if base64.urlsafe_b64encode(data).decode("ascii").rstrip("=") != s:
raise ValueError("not canonical unpadded base64url")
return data
def verify_receipt(receipt: dict, trusted_public_key: str) -> bool:
# trusted_public_key is the issuer's key, obtained from somewhere other
# than this receipt. Never use receipt["signature"]["public_key"] here:
# see "What Receipts Prove (and What They Do Not)" below.
# Fails closed: anything malformed returns False instead of raising.
if not isinstance(receipt, dict) or not isinstance(trusted_public_key, str):
return False
sig_obj = receipt.get("signature")
if not isinstance(sig_obj, dict) or sig_obj.get("alg") != "EdDSA":
return False
sig_b64 = sig_obj.get("sig")
if not isinstance(sig_b64, str):
return False
try:
# Reconstruct the payload that was actually signed (everything except signature).
payload = {k: v for k, v in receipt.items() if k != "signature"}
canonical_bytes = canonicalize(payload)
verify_key = signing.VerifyKey(b64url_decode(trusted_public_key))
verify_key.verify(canonical_bytes, b64url_decode(sig_b64))
return True
except (CryptoError, TypeError, ValueError, KeyError, OverflowError):
return False
except Exception:
# An undecodable key or signature, or a payload that cannot be
# canonicalized: fail closed rather than raise.
return False
Ez a függvény fogad egy bizonylatot és az kibocsátó nyilvános kulcsát, és True-t ad vissza, ha az aláírás érvényes, False-et pedig ellenkező esetben, beleértve a hibás bemeneteket is. Nincs hálózati hívás vagy ellenőrző szolgáltatás: amint megvan az kibocsátó kulcsa, az ellenőrzés teljesen helyi és offline. Amit még mindig megkövetel az a kulcs, amelyet a bizonylat tartalmán kívülről kell beszerezni.
Az manipuláció észlelésének szemléltetéséhez a notebook:
tool_args_hash mező egy byte-jának módosítása.A 4. lépés megértése különösen fontos. Ez a bizonylat belsőleg konzisztens: az aláírás eredeti a tartalomhoz és a benne lévő kulcshoz, így önmagával szemben sikeresen ellenőrizhető. Csak akkor bukik meg, ha az kibocsátó valódi kulcsával ellenőrizzük. A 2. és 3. lépés elkap egy támadót, aki nem vett fáradságot az újraaláírásra, a 4. lépés pedig azt, aki igen.
Ez a gyakorlati példája annak, hogy a bizonylatok manipulációérzékenyek: bármely aláírt mező megváltoztatása megszakítja az aláírást, feltéve, hogy olyannal ellenőriz, amelyet a támadó nem szolgáltatott. A signature objektum maga a aláírt byte-okon kívül van, ezért a kulcs, amivel az ellenőrzés történik, máshonnan kell, hogy származzon, nem magából a bizonylatból.
Egyetlen aláírt bizonylat egy műveletet véd. Egy bizonylatlánc egy sorozatot véd.
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
Minden bizonylat rögzíti az előző bizonylat hash-ét. Ha valaki csendben el akarja távolítani a 2. bizonylatot, akkor vagy:
previous_receipt_hash mezőjét (ez megszakítja a 3. bizonylat aláírását), VAGYHa a privát kulcs hardveres kulcstárolóban van, és az ellenőrzők minden bizonylatot összevetnek a kibocsátó nyilvános kulcsával, amelyet függetlenül szereznek be (például egy közzétett JWK Set vagy rögzített konfigurációs érték), akkor egyik támadás sem kivitelezhető észrevétel nélkül. A kulcs publikálása minden bizonylatban nem elég: egy támadó újból aláírhatja a saját kulcsával, és azt ágyazhatja be, ez az 04_resigned_receipt.json.
A notebook végigmegy a következőn:
previous_receipt_hash megegyezik az előző bizonylat tényleges hash-ével.Így állít elő olyan auditnaplót, amit egy külső auditor saját, rögzített kibocsátó kulcsaival és lánc ellenőrzőpontokkal is ellenőrizhet, anélkül, hogy a módosítható napló tárolójára kellene bíznia magát.
Ez a lecke legfontosabb része. A bizonylatok erősek, de korlátozott az erejük.
A bizonylatok három dolgot bizonyítanak:
A bizonylatok NEM bizonyítanak:
policy_id-ban hivatkozott szabályzatot ténylegesen értékelték volna, vagy hogy az engedélyezte volna ezt a műveletet. A bizonylat azt rögzíti, amit állítottak, nem ami végrehajtottak.A bizonylatban lévő kulcs nem az, amivel az ellenőrzést végzi. Ez a 3. pontból következik, és az egyetlen hely, ahol a különbség a kódját változtatja meg a megértése helyett. A fenti mintában az public_key ott van, hogy az példa önálló legyen. Az ellenőrző soha nem bízhat meg benne. Bárki vehet egy bizonylatot, módosíthatja, aláírhatja egy általuk generált kulccsal, és beágyazhatja azt a kulcsot; az eredmény önmagával szemben tökéletesen ellenőrizhető. Ez az 04_resigned_receipt.json fixture az sample_receipts/-ban, és magyarázza, hogy a fentebb verify_receipt miért fogad kulcsot argumentumként, nem pedig olvassa ki a bizonylatból. Beszerezze az kibocsátó kulcsát függetlenül, a Production Checklistben lévő JWK Setből vagy más előzetesen rögzített forrásból, és azzal ellenőrizze. Egy ugyanabba a borítékba érkezett kulccsal végzett aláírás ellenőrzés csak a boríték önkonzisztenciáját bizonyítja.
Ez a határvonal két okból fontos:
Gyakori hiba feltételezni, hogy a “van bizonylatunk” azt jelenti, hogy “irányítva vagyunk.” Nem így van. A bizonylatok alapot nyújtanak. Az irányítás az a rendszer, amit erre épít.
A 3. pont megérdemel egy külön szakaszt: egy műveletbizonylat azt mondja, “ez a kulcs írta alá ezt a tartalmat,” soha nem azt, hogy “egy ember engedélyezte ezt.” Magas kockázatú műveletek (visszatérítések, törlések, átutalások) esetén egy külön jóváhagyói aláírás kötheti össze a pontos műveletet. Az adott kulcs összekapcsolása emberrel és az ember jelenlétének ellenőrzése külön feladat marad.
A következő jegyzetfüzet, code_samples/human-authorization-receipts.ipynb, egy második típusú bizonylatot ad hozzá, human.approval.v1, ugyanabban a boríték alakban, mint a lecke bizonylatai (egy típusosított adatterhelés, amelyet Ed25519 aláír a kanonikus JCS bájtjain keresztül, az aláírt bájtokon kívül pedig az signature objektummal). Egy jóváhagyó kulcs aláírja a teljes kanonikus műveletet és annak kivonatát; egy ügynök kulcs egy állítást ír alá, amely viseli a ugyanazt a műveletkivonatot és egy parent_approval_ref, a jóváhagyás receipt_hash, ugyanaz a konvenció, mint az previous_receipt_hash a fent épített láncban. Egy verify_chain mindkét műtárgyat kezeli különálló rögzített kulcsnyilvántartások alatt (jóváhagyó kulcsok vs ügynök kulcsok), így a kódút közös, de a hatóságok soha nem.
Ez a tulajdonság, gondosan megfogalmazva: a rögzített jóváhagyó kulcs aláírta ezt a pontos műveletet, és az ügynök kulcs később aláírt egy nyilatkozatot, amely viseli ugyanazt a műveletkivonatot. Ez hasznos bizonyíték, de önmagában nem bizonyíték arra, hogy a művelet végrehajtódott. A végrehajtás ellenőrzéséhez a pontos jóváhagyást szintén meg kell őrizni, és egyszer el kell fogyasztani a tényleges végrehajtói határon; az ismeretlen szolgáltató kimeneteket ismeretlenként kell hagyni, nem pedig vakon újrapróbálkozni. A jegyzetfüzet elutasító rögzítői tesztelik a bizonylatlánc rétegét:
Minden hibát eltérő okkal utasítanak el, így egy ellenőr elolvasva az elutasítást meg tudja mondani, hogy a hatóság lejárt-e vagy a bejelentett művelet megváltozott-e. Az ellenőrzés csak olvasható és ismételhető: nem fogyasztja el a jóváhagyást és nem hív meg szolgáltatót. Egy külön végrehajtónak tartós, atomi újrajátszás elleni védelmet, valamint explicit sikeres, sikertelen és bizonytalan kimeneteleket kell kezelnie. Az emberi jóváhagyás bizonylata egy oktató jellegű kompozíció, amelyet ez a lecke határoz meg, nem pedig egy draft-farley-acta-signed-receipts által definiált bizonylattípus.
A leckében szereplő Python kód szándékosan minimális, hogy minden sort el tudj olvasni, és pontosan megérthesd, mi történik. Éles környezetben két lehetőséged van:
Építs közvetlenül a kriptográfiai primitívekre. A fent látott 50 sor sok használati esethez elegendő. A PyNaCl (Ed25519) és az jcs csomag (kanonikus JSON) jól karbantartott és auditált könyvtárak.
Használj éles környezethez készült bizonylat könyvtárat. Több nyílt forráskódú projekt valósítja meg ugyanazt a mintát további funkciókkal (kulcscsere, kötegelt ellenőrzés, JWK-készlet terjesztés, szabályzati motorok integrációja):
draft-farley-acta-signed-receipts, 02-es verzió). A lecke egyszerűsített oktató jellegű bizonylatmodellje eltér a draft {payload, signature} borítékától, és nem konform implementációként van bemutatva. A draft közzétesz egy megosztott konformancia tesztcsomagot (agent-governance-testvectors) azokhoz az implementációkhoz, amelyek a hálózati formátumát célozzák meg.protect-mcp (npm) és @veritasacta/verify (npm) csomagok egy Node alapú aláíró és offline ellenőrző megvalósítást adnak, amelyek célja, hogy bármely MCP szervert manipulációbiztos audit lánccal lássanak el, beleértve egy tartott-együtt-aláírás menetrendet is, ahol egy szüneteltetett művelet kibocsát egy jóváhagyási bizonylatot, amely kötődik a művelet lenyomatához (desktop folyamatban WebAuthn támogatással), ugyanaz a jóváhagyási bizonylat minta, mint a fenti emberi engedélyezéses jegyzetben.pip install nobulex) ugyanazt az Ed25519 + JCS aláírási mintát biztosítja Pythonban LangChain és CrewAI integrációkkal, beleértve publikált keresztvalidációs tesztvektorokat és egy megfelelőségi leképezést, amit OWASP PR #2210 révén járultak hozzá.A saját fejlesztés és a könyvtár használata közötti döntés hasonló, mint amikor JWT könyvtárat írsz saját magad vagy használsz egy tesztelt könyvtárat: mindkettő ésszerű; a könyvtár időt spórol és csökkenti az audit felületet; az alapoktól való fejlesztés megkívánja, hogy minden primitívet érts. Ez a lecke az alapoktól való utat tanítja, hogy bármelyik választáshoz meglegyen az alapod.
Teszteld az ismereteidet, mielőtt továbblépsz a gyakorlati feladathoz.
1. Egy bizonylatot az ügynök privát Ed25519 kulcsával írnak alá. Az auditor csak a nyilvános kulccsal rendelkezik. Tudja az auditor offline ellenőrizni a bizonylatot?
2. Egy támadó módosítja a bizonylat policy_id mezőjét, hogy azt állítsa, lazább szabályzás vonatkozott rá. Az aláírás az eredeti terhelésen készült. Mi történik az ellenőrzés során?
3. Miért tartalmaz a bizonylat egy tool_args_hash és egy result_hash mezőt a nyers argumentumok és eredmény helyett?
4. A previous_receipt_hash mező minden bizonylatot összeköt az elődjével. Ha egy támadó csendben töröl egy bizonylatot a lánc közepéről, mi válik érvénytelenné?
5. Egy bizonylat tisztán ellenőrződik. Bizonyítja ez, hogy az ügynök művelete helyes, érvényes vagy szabályzatnak megfelelő volt?
Nyisd meg code_samples/18-signed-receipts.ipynb fájlt és teljesítsd mind a négy részt:
Kihívás 1: bővítsd a bizonylat sémát egy általad választott további mezővel (például egy kérés azonosítóval a nyomon követéshez), frissítsd a kanonikus aláírás logikát, hogy tartalmazza ezt, és erősítsd meg, hogy a bizonylat még mindig sikeresen körbefut az ellenőrzésen. Ezután módosítsd a mezőt az aláírás után, és erősítsd meg, hogy az ellenőrzés sikertelen lesz. Ez kényszerít rá, hogy megértsd, hogyan járul hozzá a kanonikus kódolás minden bájtja az aláíráshoz.
Kihívás 2: SHA-256-tal hashezd össze két bizonylatodat (kötve össze a kanonikus bájtjaikat determinisztikus sorrendben), és ágyazd be az eredő lenyomatot egy harmadik bizonylat új mezőjében az aláírás előtt. Ellenőrizd, hogy mindhárom bizonylat továbbra is sikeresen ellenőrizhető. Így egy lépéses befogadási bizonyítékot hoztál létre: aki birtokolja a harmadik bizonylatot, bizonyíthatja, hogy az első két bizonylat létezett az aláírás időpontjában, anélkül, hogy felfedné azok tartalmát. Ez a minta az, amit a szelektív nyilvánosságra hozatalú bizonylatok használnak nagyszabásúan (Merkle elköteleződések, RFC 6962).
A kriptográfiai bizonylatok audit nyomot adnak az AI ügynököknek, amely:
Nem helyettesítik az inputellenőrzést, szabályzat végrehajtást, futtatói engedélyezést, kimeneti bizonyítékot, teljességi ellenőrzéseket vagy azonosítási infrastruktúrát. Ezeknek a rétegeknek az alapját jelentik. Szabályozott vagy több szervezetet érintő munkafolyamatokban a bizonylatok az egyedi kiállítói állításokat függetlenül ellenőrizhetővé teszik az auditor saját bizalmi konfigurációja alatt.
A legfontosabb tanulság: a bizonylatok bizonyítják, hogy egy adott kulcs adott tartalmat írt alá. A hordozott időbélyeg aláírói állítás, hacsak nincs külön időpecsét. Egy bizonylat nem bizonyítja, hogy a tartalma igaz volt, hogy egy művelet megtörtént, vagy hogy az adatgyűjtemény teljes. Ezeket a különbségeket tartsd szigorúan.
Amikor készen állsz arra, hogy kilépj ebből a leckéből, és éles bizonylat-aláírt ügynököket telepíts:
Csatlakozz a Microsoft Foundry Discord szerverhez, hogy találkozz más tanulókkal, részt vegyél nyitvatartási órákon, és választ kapj AI ügynökök kapcsán.
Ez a lecke az egyedi bizonylat aláírást és a hash-láncolt sorozatokat fedi le. Ugyanezek a primitívek több haladó mintában komponálódnak, amelyekkel találkozhatsz, ahogy érlelődik a kormányzási pozíciód:
authorization_*) és végrehajtás utáni (result_*) felére bontják, ami hasznos, ha az engedélyezési döntést és a megfigyelt eredményt különböző szereplők vagy különböző időpontokban hozzák létre. Ez additív módon épül be a jelen leckében tanult bizonylat-formátumra.result_hash-be helyezett bájtokat. A valós terhelések gyakran gazdagabbak, mint egyetlen eszközhívás eredménye: a döntés előtti érvelés (modell-előrejelzés, mérlegelt opciók, bizonyíték és annak teljessége, kockázati helyzet, elszámoltathatósági lánc, kapu eredménye) mind a terhelés része lehet, amelyet egyetlen bizonylattal zárnak le. Ez minimalizálja a bizonylatformátumot, miközben engedi, hogy a terhelési sémák domainekre bontva fejlődjenek.alg címke önmagában nem migráció: egy profilnak definiálnia kell az ML-DSA kulcskódolást, a kanonikus aláírt bájtokat, az ellenőrzést, a megbízó fél politikáját, a visszalépés elleni védelmet és az átmeneti szemantikát. Tervezd meg és teszteld a két aláírásos átmenetet közös vektorokon, mielőtt kompatibilitási állításokat teszel.Jogi nyilatkozat: Ez a dokumentum az AI fordítási szolgáltatás, a Co-op Translator segítségével készült. Bár az pontosságra törekszünk, kérjük, vegye figyelembe, hogy az automatikus fordítások hibákat vagy pontatlanságokat tartalmazhatnak. Az eredeti dokumentum az anyanyelvén tekintendő hiteles forrásnak. Fontos információk esetén professzionális emberi fordítást javasolunk. Nem vállalunk felelősséget semmilyen félreértésért vagy téves értelmezésért, amely ebből a fordításból ered.