Titta på lektionsvideon: Säkerställa AI-agenter med kryptografiska kvitton
(Lektionsvideo och miniatyrbild kommer att läggas till av Microsofts innehållsteam efter sammanslagning, matchande lektionsmönstret 14 / 15.)
Den här lektionen täcker:
Efter att ha genomfört denna lektion kommer du att veta hur man:
Föreställ dig att du har lanserat en AI-agent för Contoso Travel. Agenten läser kundförfrågningar, anropar en flyg-API för att leta upp alternativ och bokar platser för kundens räkning. Förra kvartalet behandlade agenten 50 000 bokningar.
Idag anländer en revisor. De ställer en enkel fråga: “Visa mig vad din agent gjorde.”
Du överlämnar dina loggfiler. Revisorn tittar på dem och ställer den svårare frågan: “Hur vet jag att dessa loggar inte har redigerats?”
Detta är problemet med revisionsspår. De flesta agentdistributioner idag förlitar sig på:
Ingen av dessa kan svara på revisorns fråga utan att revisorn måste lita på någon (dig, din molnleverantör, din databassäljare). För intern användning är det ofta acceptabelt. För reglerade arbetsbelastningar (finans, sjukvård, allt som omfattas av EU:s AI-förordning) är det inte det.
Kryptografiska kvitton begränsar detta problem genom att göra ett undertecknat uttalande oberoende verifierbart. Revisorn behöver fortfarande en extern anledning att lita på signeringsnyckeln och komponenten som producerade uttalandet. En inbäddad nyckel bevisar självkonsekvens, inte utfärdaridentitet eller kontrollplacering.
Ett kvitto är ett JSON-objekt som registrerar vad en agent gjorde, signerat med en digital signatur.
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]
Ett minimalt kvitto ser ut så här:
{
"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..."
}
}
Tre egenskaper utför jobbet:
Signaturen. Kvittot signeras av agentens gateway med en privat Ed25519-nyckel. Vem som helst med motsvarande offentlig nyckel kan verifiera signaturen offline. En beroende part måste låsa fast den nyckeln eller hämta den från ett betrott register utanför kvittot. Manipulation med något signerat fält ogiltigförklarar signaturen.
Kanonisk kodning. Innan signering serialiseras kvittot med JSON Canonicalization Scheme (JCS, RFC 8785). Detta säkerställer att två implementationer som producerar samma logiska kvitto genererar byte-identiskt output. Utan kanonisering skulle olika JSON-serialiserare producera olika signaturer för samma innehåll.
Hash-kedjning. Fältet previous_receipt_hash länkar varje kvitto till det föregående. Att ta bort eller omordna ett kvitto bryter den presenterade sekvensen. Att upptäcka trunkering eller en signatörskontrollerad omskrivning kräver också ett låst aktuellt kedjehuvud, oberoende bevittnat kontrollpunkt eller autentiserat slutet populationsåtagande.
Tillsammans ger dessa egenskaper tre garantier:
Du behöver inget särskilt bibliotek för att skapa ett kvitto. De kryptografiska primitiven finns allmänt tillgängliga och logiken är några tiotals rader Python.
De praktiska övningarna i code_samples/18-signed-receipts.ipynb går igenom hela flödet. Den versionshanterade code_samples/18-signed-receipts.execution-receipt.json registrerar exakt notebook-hash, Python-miljö, cellantal och kontroller från senaste rena körningen utan att ändra lektionens sparade resultat. Sammanfattad version:
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)),
},
}
Det är hela signeringspipen. Övningarna i notebooken går igenom varje steg.
Verifiering är den omvända operationen:
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
Den här funktionen tar ett kvitto och utgivarens offentliga nyckel och returnerar True om signaturen är giltig och False annars, även när indata är felaktig. Inget nätverksanrop och ingen verifieringstjänst: när du har utgivarens nyckel är verifiering helt lokal och offline. Vad det fortfarande kräver är den nyckeln, hämtad från någon annanstans än själva kvittot.
För att se manipulation upptäckas i praktiken går notebooken igenom:
tool_args_hash.Steg 4 är det värt att fundera på. Det kvittot är internt konsekvent: dess signatur är äkta för dess innehåll och för den nyckel det bär, så det verifieras mot nyckeln inuti. Det misslyckas bara när det kontrolleras mot utgivarens riktiga nyckel. Steg 2 och 3 fångar en angripare som inte orkade signera om; steg 4 fångar den som gjorde det.
Detta är den praktiska demonstrationen att kvitton är manipulationssäkra: varje ändring av ett signerat fält bryter signaturen, förutsatt att du verifierar mot en nyckel som angriparen inte levererat. Själva objektet signature ligger utanför de signerade bytena, vilket är varför nyckeln du verifierar mot måste komma från någon annan källa än kvittot.
Ett enda signerat kvitto skyddar en handling. En kedja av kvitton skyddar en sekvens.
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
Varje kvitto registrerar hashen av kvittot före det. För att tyst ta bort kvitto 2 skulle en angripare behöva antingen:
previous_receipt_hash i kvitto 3 (bryter kvitto 3:s signatur), ELLEROm den privata nyckeln finns i en hårdvarunyckelvalv och verifierare kontrollerar varje kvitto mot utgivarens offentliga nyckel, som hämtats oberoende (en publicerad JWK Set eller ett låst konfigurationsvärde), är ingen attack möjlig utan upptäckt. Att publicera nyckeln inuti varje kvitto räcker inte: en angripare kan signera om med sin egen nyckel och istället bädda in den, vilket är fällan 04_resigned_receipt.json.
Notebooken går igenom:
previous_receipt_hash stämmer överens med den faktiska hashen av det föregående kvittot.Så här producerar du ett revisionsspår som en extern revisor kan verifiera under sina egna låsta utgivarnycklar och kedjekontroller, utan att behöva lita på din oföränderliga loggdatabas.
Detta är den viktigaste delen av lektionen. Kvitton är kraftfulla men deras kraft är begränsad.
Kvitton bevisar tre saker:
Kvitton bevisar INTE:
policy_id faktiskt utvärderades, eller att den skulle ha tillåtit denna handling om den kontrollerats. Kvittot registrerar vad som påstods, inte vad som efterlevdes.Nyckeln i kvittot är inte den nyckel du verifierar med. Detta följer från punkt 3, och det är den enda plats där skillnaden måste ändra din kod snarare än din förståelse. public_key i exemplet ovan finns där så att exemplet är självförsörjande. En verifierare får aldrig lita på den. Vem som helst kan ta ett kvitto, ändra det, signera det med en nyckel de genererat och bädda in den nyckeln; resultatet verifierar perfekt mot sig självt. Det är fällan 04_resigned_receipt.json i sample_receipts/, och det är därför verify_receipt ovan tar nyckeln som argument istället för att läsa ut den från kvittot. Skaffa utgivarens nyckel oberoende, från JWK Set i produktionskontrollistan nedan eller en annan förankring du låst fast i förväg, och verifiera mot den. En signatur kontrollerad med en nyckel som kommit i samma kuvert bevisar bara att kuvertet är självkonsekvent.
Den här gränsen är viktig av två skäl:
Ett vanligt misstag är att anta att “vi har kvitton” betyder “vi är styrda.” Det gör det inte. Kvitton är en grund. Styrning är systemet du bygger ovanpå.
Punkt 3 ovan är värd en egen sektion: ett handlingskvitto säger “denna nyckel signerade detta innehåll,” aldrig “en människa godkände detta.” För högriskhandlingar (återbetalningar, borttagningar, banköverföringar) kan en separat godkännares signatur binda exakt handling. Att koppla den nyckeln till en människa och kontrollera mänsklig närvaro är fortfarande separata ansvar.
Följande notebook code_samples/human-authorization-receipts.ipynb lägger till en andra kvittotyp, human.approval.v1, i samma kuvertform som lektionens kvitton (en typad payload signerad med Ed25519 över dess kanoniska JCS-byten, med objektet signature utanför de signerade bytena). En godkännar-nyckel signerar hela den kanoniska handlingen och dess digest; en agentnyckel signerar ett påstående som bär samma handlingsdigest och ett parent_approval_ref, receipt_hash för godkännandet, samma konvention som previous_receipt_hash i kedjan du byggde ovan. En verify_chain verifierar båda artefakterna under separata låsta nyckelregister (godkännar-nycklar vs agent-nycklar), så kodvägen delas men myndigheterna aldrig.
Egenskapen detta skänker, uttryckt noggrant: den låsta godkännar-nyckeln signerade denna exakta handling, och agentnyckeln signerade senare ett påstående som bär samma handlingsdigest. Det är användbara bevis, men det är inte i sig själv bevis på att handlingen utfördes. För att kontrollera utförandet måste det exakta godkännandet också reserveras och konsumeras en gång vid den faktiska utförargränsen; okända leverantörsresultat måste förbli okända snarare än att blint försöka igen. Notebookens vägras-fällor testar kvittokedjans lager:
Varje fel nekas med en distinkt anledning, så en revisor som läser en vägran kan avgöra om myndigheten gått ut eller om den påstådda handlingen ändrades. Verifiering är skrivskyddad och upprepbar: den konsumerar inte godkännandet eller anropar en leverantör. En separat utförare behöver hållbart, atomärt skydd för uppspelning och uttryckliga resultat för framgång, misslyckande och osäkert. Det mänskliga godkänningskvittot är en pedagogisk sammansättning definierad av denna lektion, inte en kvittotyp definierad av draft-farley-acta-signed-receipts.
Python-koden i denna lektion är avsiktligt minimal så att du kan läsa varje rad och förstå exakt vad som händer. I produktion har du två alternativ:
Bygg direkt på de kryptografiska primitives. De 50 rader du såg ovan är tillräckliga för många användningsfall. PyNaCl (Ed25519) och jcs-paketet (kanonisk JSON) är väl underhållna och granskade bibliotek.
Använd ett produktionsklart kvitto-bibliotek. Flera open-source-projekt implementerar samma mönster med ytterligare funktioner (nyckelrotation, batchverifiering, JWK Set-distribution, integration med policy-motorer):
draft-farley-acta-signed-receipts, revision 02). Denna lektionens enkla utbildningskvitto skiljer sig från utkastets {payload, signature}-kuvert och presenteras inte som en konform implementering. Utkastet publicerar en delad konformitetssvit (agent-governance-testvectors) för implementationer som riktar sig mot dess trådadapterformat.protect-mcp (npm) och @veritasacta/verify (npm)-paketen tillhandahåller en Node-baserad implementation av kvitto-signering och offline-verifiering, avsedd för att omsluta vilken MCP-server som helst med en manipuleringssäker revisionskedja, inklusive ett hold-for-ko-sign-flow där en pausad åtgärd genererar ett godkännandekvitto bundet till åtgärdens digest (WebAuthn-stödd i desktopflödet), samma godkännandekvittomönster som den ovan i människobaserad auktoriseringsanteckningsbok.pip install nobulex) tillhandahåller samma Ed25519 + JCS signeringsmönster i Python med integrationer för LangChain och CrewAI, inklusive publicerade korsvaliderings-testvektorer och en överensstämmelsekarta bidragen via OWASP PR #2210.Beslutet mellan att skapa eget och att använda ett bibliotek speglar beslutet mellan att skriva ett eget JWT-bibliotek och använda ett testat: båda är rimliga; biblioteket sparar tid och minskar revisionsbredden; från-grunden-metoden tvingar dig att förstå varje primitiv. Den här lektionen lär ut från-grunden-vägen så att du har grunden för båda valen.
Testa din förståelse innan du går vidare till övningsuppgiften.
1. Ett kvitto signeras med agentens privata Ed25519-nyckel. Revisor har endast den publika nyckeln. Kan revisorn verifiera kvittot offline?
2. En angripare ändrar policy_id-fältet i ett kvitto för att hävda att det styrdes av en mer tillåtande policy. Signaturen var över den ursprungliga nyttolasten. Vad händer vid verifiering?
3. Varför inkluderar kvittot en tool_args_hash och result_hash istället för de råa argumenten och resultatet?
4. Fältet previous_receipt_hash länkar varje kvitto till dess föregångare. Om en angripare tyst raderar ett kvitto från mitten av en kedja, vad blir ogiltigt?
5. Ett kvitto verifieras utan fel. Bevisar det att agentens åtgärd var korrekt, rimlig eller överensstämmande med policyn?
Öppna code_samples/18-signed-receipts.ipynb och slutför alla fyra sektioner:
Utmaning 1: Utöka kvittoschemat med ett extra fält efter eget val (t.ex. en begäran-ID för spårning), uppdatera den kanoniska signeringslogiken för att inkludera det, och bekräfta att kvittot fortfarande genomgår verifiering utan problem. Modifiera sedan fältet efter signering och bekräfta att verifieringen misslyckas. Detta tvingar dig att förstå hur varje byte i den kanoniska kodningen bidrar till signaturen.
Stretch-uppgift 2: Sha256-hasha två av dina kvitton tillsammans (sammanfoga deras kanoniska byte i en deterministisk ordning) och bädda in den resulterande digesten som ett nytt fält på ett tredje kvitto innan du signerar det. Verifiera att alla tre kvitton fortfarande kan återläsa varandra. Du har precis byggt ett ettstegs inkluderingsbevis: vem som helst som har det tredje kvittot kan bevisa att de två första fanns när det signerades, utan att behöva avslöja deras innehåll. Detta är mönstret som kvitton för selektiv avslöjande använder i skala (Merkle-åtaganden, RFC 6962).
Kryptografiska kvitton ger AI-agenter en revisionskedja som är:
De ersätter inte inputvalidering, policyuppföljning, exekutörsbehörighet, resultatbevis, fullständighetskontroller eller identitetsinfrastruktur. De är en grund för dessa lager. I reglerade eller flerorganisatoriska arbetsflöden gör kvitton specifika utfärdaruttalanden självständigt kontrollerbara under granskarnas egen tillitskonfiguration.
Den viktigaste slutsatsen: kvitton bevisar att en viss nyckel signerat ett visst innehåll. En medföljande tidsstämpel är ett påstående från signaturen om det inte är tidstämplat separat. Ett kvitto bevisar inte att dess innehåll var sant, att en åtgärd utfördes eller att uppsättningen poster är fullständig. Håll dessa skillnader tydliga.
När du är redo att gå vidare från den här lektionen till att distribuera kvitto-signerade agenter i en riktig miljö:
Gå med i Microsoft Foundry Discord för att träffa andra elever, delta i kontorstid och få svar på dina frågor om AI-agenter.
Denna lektion täcker signering av enstaka kvitton och hash-kedjade sekvenser. Samma primitiva byggstenar utgör flera mer avancerade mönster som du kan stöta på när din styrningsposition mognar:
authorization_*) och efterutförande (result_*) halvor med oberoende signaturer, användbart när auktorisationsbeslutet och det observerade resultatet produceras av olika aktörer eller vid olika tider. Detta bygger på kvittoformatet som lärs ut i denna lektion.result_hash. Verkliga nyttolaster är ofta rikare än ett enskilt verktygsresultat: resonemang före beslut (modellprediktion, övervägda alternativ, bevis och dess fullständighet, riskställning, ansvarskedja, portutfall) kan allt finnas inom nyttolasten, förseglad av ett enda kvitto. Detta håller kvittoformatet minimalt samtidigt som nyttolastscheman kan utvecklas domän för domän.alg-etikett ensam är inte en migration: en profil måste definiera ML-DSA nyckelkodning, kanoniska signerade bytes, verifiering, beroendeparts-policy, nedgraderingsmotstånd och övergångssemantik. Planera och testa en övergång med dubbla signaturer mot gemensamma vektorer innan kompatibilitetsanspråk görs.Ansvarsfriskrivning: Detta dokument har översatts med hjälp av AI-översättningstjänsten Co-op Translator. Även om vi strävar efter noggrannhet, var vänlig notera att automatiska översättningar kan innehålla fel eller brister. Det ursprungliga dokumentet på dess modersmål bör betraktas som den auktoritativa källan. För kritisk information rekommenderas professionell mänsklig översättning. Vi ansvarar inte för några missförstånd eller feltolkningar som uppstår till följd av användningen av denna översättning.