Bevispaket: en signerad registrering av en GNSS-förtroendehändelse

Ett paket är en teknisk registrering, inte ett juridiskt utlåtande. Det anger vad Kshana-motorn beräknade utifrån en angiven mottagarlogg under en angiven konfiguration, och låter vem som helst kontrollera att inget i det ändrades efteråt. Det säger inte vad som orsakade en händelse, vem som var ansvarig, om någon skyldighet uppfylldes, eller att loggen visar vad mottagaren verkligen tog emot. Manifestet och sammanfattningen säger båda detta.

Ett bevispaket är till för en incidentrapport, en försäkringsgivare eller en myndighetsfråga: "vad sade ert system om GNSS-signalen mellan dessa två tidpunkter, och kan vi lita på den registreringen?"

Skapa ett paket#

# once: a signing key. The private key stays with you; never commit it.
kshana evidence keygen --out signer.key        # writes signer.key (0600) and signer.key.pub

kshana receiver-trust evidence session.toml \
    --from 100 --to 260 \                       # seconds since the first epoch, or ISO-8601 UTC
    --key signer.key --out pack/ \
    --title "Berth 4, 14 June"                  # optional

För ett paket som skapats från en laboratoriesession registrerar --lab-attestation lab.toml operatörens uttalande om uppställningen (ledningsbunden eller skärmad, dämpning eller kapsling, vad som sände ut eventuell RF) i det signerade manifestet; se HARDWARE-SAFETY.md. Det registreras som det angavs och verifieras aldrig.

--from och --to är sekunder sedan loggens första epok, eller en ISO-8601 UTC-tid när loggen anger sin egen starttid. --out får inte redan innehålla filer. --created-utc tar en verklig UTC-tid som 2026-01-02T03:04:05Z (allt annat avvisas) eller none, vilket utelämnar skapandetiden och gör paketet byte för byte reproducerbart. Skapandetiden är vad undertecknaren anger; ingenting kontrollerar den mot en klocka, vilket är vad den valfria tidsstämpelstoken är till för.

Nyckelfilen innehåller ett Ed25519-frö på 32 byte som 64 hexadecimala siffror; ange ditt eget (till exempel ett som förvaras i ditt nyckelhanteringssystem) eller låt keygen skapa ett. kshana varnar om filen kan läsas av andra användare. .gitignore utesluter *.evidence-key; ge din nyckel ett sådant namn om den ligger i en utcheckad kopia.

Vad ett paket innehåller#

Loggutsnitt. Läsaren redovisar källans byteintervall för varje epok, så utsnittet är det minsta byteintervall som rymmer varje epok i fönstret (byte-range): NMEA, u-blox UBX, RINEX 3-observationer och Android-loggar. Det hashas som råa bytes, aldrig som avkodad text. För en direktström eller RINEX 2 finns inget intervall; hela loggen medföljer då och manifestet säger whole-log (fönstret begränsar vilka epoker som redovisas, inte vilka bytes som ingår). Sammanfattningen anger vilket som gäller. Ett utsnitt är en registrering av fönstrets bytes, inte en fristående logg: till exempel har ett RINEX-utsnitt inget filhuvud.

Hashkedja. Manifestet listar filerna i fast ordning. link₀ = SHA-256("kshana- evidence-chain/1"); för varje fil, linkᵢ = SHA-256(linkᵢ₋₁ ‖ SHA-256(file) ‖ len(name) ‖ name) (längd som 4 bytes, big-endian). Den sista länken är chain_head. Att ändra ordning på, ta bort eller byta ut en fil ändrar kedjan; signaturen täcker kedjan.

Verifiera ett paket#

kshana evidence verify pack/ --pubkey signer.key.pub [--log session.nmea] \
    [--require-timestamp] [--allow-unpinned] [--json]

Slutstatus 0 betyder verifierat; 1 betyder att något misslyckades; 2 betyder ett användningsfel; 3 betyder att paketet är intakt men att dess undertecknare inte var fastlåst (se nedan). Varje kontroll rapporterar godkänd, underkänd eller hoppad över, och varje fel namnges:

Att ändra en enda byte i någon fil gör att verifieringen misslyckas med motsvarande skäl: en ändrad artefakt rapporteras som den filens hashavvikelse och inget annat; ett ändrat manifest gör att signaturen misslyckas. Att räkna om hashvärden och kedjan efter att en fil redigerats hjälper inte utan signeringsnyckeln; då är det bara signaturen som misslyckas.

Lås fast nyckeln. Utan --pubkey bevisar ett paket bara att det är intakt mot den nyckel det själv anger, som vem som helst kan generera. Verifieringen avslutas därför med 3 och säger "INTACT, BUT THE SIGNER IS NOT PINNED" i stället för "VERIFIED"; --allow-unpinned godtar paketets egen nyckel med öppna ögon och skriver "VERIFIED against the key the pack names itself (signer NOT pinned; pass --pubkey)". Hämta undertecknarens publika nyckel från undertecknaren på en väg du litar på (inte från paketet) och ange den med --pubkey: 64 hexadecimala siffror eller filen .pub. Att av misstag ange den privata nyckeln känns igen och avvisas. Fingeravtrycket (de första 128 bitarna av nyckelns SHA-256, 32 hexadecimala siffror) skrivs ut för att jämföras med blotta ögat; att låsa fast hela nyckeln är den pålitliga vägen.

Paketformat och verifieringsprocedur (normativt)#

Det här avsnittet är den specifikation som en oberoende verifierare skrivs utifrån. Ord med versaler är krav. Ett paket är en katalog (eller vilken avbildning som helst från filnamn till bytes) med filer som heter exakt som nedan; en verifierare arbetar med bytena i varje fil så som de är lagrade och serialiserar aldrig om något.

Filer. Artefaktfilerna, i denna fasta ordning, är log-slice.bin, config.json, epochs.json, summary.html. Ett paket har också manifest.json och manifest.sig, och KAN ha timestamp.tsr. Varje annat namn är en olistad fil.

Hex. Varje hexsträng består enbart av gemena 0-9a-f, utan blanksteg; versaler godtas inte. SHA-256-värden är 64 siffror, den publika nyckeln är 64 siffror, signaturen är 128 siffror.

manifest.sig. Den hexadecimala texten med 128 siffror och gemener för den 64 byte långa Ed25519-signaturen (RFC 8032, det rena Ed25519-schemat) över de exakta bytena i manifest.json, följd av exakt en \n och inget annat. Signaturen MÅSTE kontrolleras strikt: en signatur vars S-värde inte är mindre än gruppordningen L är ogiltig.

manifest.json. Ett UTF-8 JSON-objekt. Dess medlemmar (en verifierare MÅSTE hitta var och en med den angivna JSON-typen; ytterligare medlemmar ignoreras):

signer.fingerprint är de första 32 hexadecimala siffrorna av SHA-256 över de 32 byten i den publika nyckeln.

Hashkedja. link0 är SHA-256 av de 23 ASCII-byten kshana-evidence-chain/1. För varje artefakt i ordning, link = SHA-256( previous_link (32 bytes) ‖ SHA-256(file) (32 bytes) ‖ len(name) as 4 bytes big-endian ‖ name as UTF-8 ), där SHA-256(file) hämtas från manifestets registrerade sha256 för den artefakten (så kedjan är en egenskap hos manifestet och kontrolleras mot det, inte mot filerna).

Procedur. En verifierare utför dessa steg i ordning och samlar varje fel; resultatet är mängden fel, vart och ett en code och, där det anges, filens name. Den FÅR INTE stanna vid det första felet utom där det anges. pin är den publika nyckel som verifieraren fått veta att den ska lita på, om någon.

1. Ingen manifest.json: fel manifest-missing; stanna.
2. Om manifest.json inte är ett JSON-objekt med varje medlem ovan i angivna typer (inklusive artifacts-poster med varje medlem, och log.slice): fel manifest-malformed. Annars, om format inte är det värde som anges ovan: unsupported-format.
3. Signaturfas. Den här fasen utförs oavsett om manifestet gick att läsa. Om manifestet gick att läsa är den angivna nyckeln signer.public_key; om den inte är 64 hexadecimala siffror med gemener, fel public-key-malformed (ingen angiven nyckel); annars, om signer.fingerprint inte är fingeravtrycket av den, fel public-key-malformed (nyckeln förblir användbar). Om både en pin och en angiven nyckel finns och skiljer sig åt: fel public-key-mismatch. Kontrollnyckeln är pin om en angavs, annars den angivna nyckeln om det finns en; med ingen av dem finns ingen kontrollnyckel (detta gäller varje fall där manifestet inte gick att läsa och ingen pin angavs). Om det inte finns någon manifest.sig: signature-missing. Annars, om filen inte är exakt 128 hexadecimala siffror med gemener plus en \n: signature-malformed. Annars, om det finns en kontrollnyckel som inte är en giltig kodning av en publik Ed25519-nyckel: public-key-malformed. Annars, om det finns en kontrollnyckel och signaturen inte verifieras strikt över bytena i manifest.json (vad de än är): signature-invalid. (Utan kontrollnyckel kontrolleras inte signaturen och inget fel uppstår för det.)
4. Om manifestet inte gick att läsa (steg 2 gav manifest-malformed): stanna här.
5. Artefakter. Om namnen i artifacts inte exakt är de fyra ovan i ordning: artifact-list-malformed. Sedan, för varje manifestpost i ordning: om paketet inte har någon fil med det namnet, file-missing (namn); annars, om dess längd skiljer sig från bytes, file-size-mismatch (namn); och, oberoende av det, om SHA-256 för filen skiljer sig från sha256, file-hash-mismatch (namn).
6. Olistade filer: för varje fil i paketet utöver manifest.json, manifest.sig, timestamp.tsr och namnen i manifestets artifacts: unlisted-file (namn).
7. Kedja. Gå igenom manifestets artifacts i ordning från link0. Om en posts sha256 inte är 64 hexadecimala siffror med gemener: manifest-malformed och kedjan överges (ingen kontroll av huvudet). Annars beräknas länken; om den skiljer sig från postens link: chain-mismatch (namn). Efter genomgången, om kedjan inte övergavs och den sista länken skiljer sig från chain_head: chain-head-mismatch.
8. Utsnitt och epoker. Utlös slice-record-inconsistent (högst en gång per skäl, och en verifierare rapporterar koden en gång oavsett hur många skäl som gäller) om något av: start > end; end > full_bytes; postens log-slice.bin har ett sha256 som skiljer sig från slice.sha256; den postens bytes skiljer sig från end - start; eller kind är whole-log och något av start != 0, end != full_bytes, slice.sha256 != full_sha256. Om epochs.json finns och tolkas som en JSON-matris vars längd skiljer sig från epochs_in_window: epoch-count-mismatch.
9. Hela loggen. Endast om verifieraren fick de ursprungliga logg-bytena: om deras SHA-256 skiljer sig från log.full_sha256, full-log-hash-mismatch; annars, om intervallet start..end inte ligger inom loggen eller om loggens bytes där skiljer sig från log-slice.bin, slice-not-from-full-log.
10. Tidsstämpel. Utan timestamp.tsr: om verifieraren fått veta att den ska kräva en, timestamp-missing; annars ingenting. Med en: om den inte kan läsas som en token eller ett svar enligt RFC 3161 (se nedan), timestamp-malformed; annars, om dess meddelandeavtryck inte är hashvärdet, med avtryckets egen algoritm (SHA-256, SHA-384 eller SHA-512), av bytena i manifest.json: timestamp-imprint-mismatch.

Paketet är verifierat exakt när felmängden är tom. Om undertecknaren var fastlåst rapporteras separat och ändrar inte felmängden.

Tidsstämpelstoken. En token är en DER-kodad ContentInfo vars innehållstyp är CMS SignedData (1.2.840.113549.1.7.2) och vars inkapslade innehållstyp är id-ct-TSTInfo (1.2.840.113549.1.9.16.1.4); ett svar är ett DER-kodat TimeStampResp (en PKIStatusInfo följd av token) vars status är 0 eller 1. Algoritmen för meddelandeavtrycket i TSTInfo måste vara SHA-256, SHA-384 eller SHA-512 med ett kondensat av den algoritmens längd, och dess genTime en verklig UTC-kalendertid. BER med obestämd längd godtas inte. Myndighetens signatur och certifikatkedja kontrolleras endast när betrodda ankare anges (--tsa-ca, nedan).

Evidensetiketten (0,40)#

Ett paket byggt med 0,40 eller senare bär, inuti config.json, en post evidence (nivån, VALIDATED, MODELLED eller PARTNER, som är den svagaste statusen bland dess rader, samt id:na och kraven för de rader i verifieringsmatrisen som paketets innehåll vilar på: raden för paketets integritet, raderna för receiver-trust, och raderna för jammertest-poängsättning eller rundtur för sådana paket) och config_version "1.1". Den ligger inuti config.json, så manifestets filhash, hashkedjan och signaturen täcker den: att ändra den gör att verifieringen misslyckas. kshana evidence verify redovisar nivån och radernas id.

Ändringen är additiv och gäller bara framåt. Manifestets format förblir kshana-evidence/1: den normativa texten ovan säger att en verifierare MÅSTE hitta det värdet, och verifieraren byggd från rent blad i scripts/ gör det. Den lägre versionen bärs därför av config_version (saknas för ett paket gjort före 0,40, vilket betyder 1,0), inte av en ny sträng format. Ett paket gjort före 0,40 har ingen etikett och verifieras oförändrat; kshana evidence verify säger "no evidence label (pre-0.40 pack)". Testerna är tests/evidence_pack_label.rs (inklusive de incheckade oberoende paketen från före 0.40) och tests/evidence_labels_doc_sync.rs.

Tidsstämpel enligt RFC 3161 (valfri)#

En tidsstämpelstoken från en tidsstämpelmyndighet visar att manifestet fanns vid en tidpunkt som myndigheten intygar. Token gäller manifest.json, så den begärs efter att paketet skapats (det går inte att ange en när paketet skapas, och create_bundle avvisar en token som inte gäller exakt det manifestet):

openssl ts -query -data pack/manifest.json -sha256 -cert -out req.tsq
# send req.tsq to your authority, get the response, then:
kshana evidence attach-timestamp pack/ response.tsr
openssl ts -verify -in response.tsr -data pack/manifest.json -CAfile authority-ca.pem

kshana evidence verify läser token (en ren token eller ett fullständigt svar), kontrollerar att den beviljades och att dess meddelandeavtryck är lika med hashvärdet av manifest.json, och skriver ut den tid den anger. Utan betrodda ankare lägger den till "timestamp authority signature not verified by Kshana" och rapporterar authority_signature_verified: false; kör raden openssl ts -verify ovan för den delen. En token vars avtryck skiljer sig, eller som inte går att tolka, är ett fel. Tokenens innehållstyper, avtryckslängd och genereringstid kontrolleras för rimlighet.

Med --tsa-ca authority-ca.pem (ett eller flera PEM-certifikat, alla betrodda) kontrollerar verify också myndigheten, offline, på det sätt som openssl ts -verify gör: de signerade attributens meddelandekondensat, signaturen (RSA PKCS#1 v1.5, RSA-PSS, ECDSA P-256 eller P-384), ESS-bindningen till signeringscertifikatet, undertecknarens kritiska utökade nyckelanvändning timeStamping och kedjan till ett självutfärdat ankare, där varje certifikat är giltigt vid tokenens genTime. Ett fel rapporteras som timestamp-authority-invalid med den första kontroll som misslyckades, och authority_signature_verified är sant endast när allt godkändes. Återkallelse (CRL eller OCSP) kontrolleras inte. Den här verifieraren stämmer överens med OpenSSL 3.0.13 på 27 självgenererade fall (tests/fixtures/evidence_tsa/PREREGISTRATION.md).

Token ligger bredvid det signerade manifestet, inte i det. Ingenting i signaturen eller kedjan täcker den, så en token kan tas bort, eller en annan giltig token sättas in, utan att signaturen misslyckas. verify noterar därför när ett paket saknar en, och --require-timestamp gör en saknad token till ett fel (timestamp-missing); en utbytt token upptäcks bara om den inte matchar manifestet. attach-timestamp vägrar skriva över en befintlig token om du inte anger --replace. Om en tidsstämpel är viktig för dig, behåll token och verifieringsresultatet bland dina egna uppgifter, och kräv den.

Från kod#

kshana::evidence::build_receiver_trust_pack är den enda ingångspunkt som kommandoraden och varje annan yta anropar för att skapa ett paket: ett scenario, loggens bytes (och navigeringsfilens, för RINEX), fönstret som text, en titel och en valfri skapandetid, plus signeringsfröet, in; filerna, antalet epoker, utsnittet, manifestets hashvärde och undertecknarens fingeravtryck ut. Den läser inga filer och ingen klocka, så samma indata ger samma bytes. Under den är create_bundle och verify_bundle rena funktioner: bytes in (EvidenceInput, ett frö på 32 byte, en BTreeMap<String, Vec<u8>> av filer), serialiserbara resultat ut (Files, VerifyReport). De använder inga filer, ingen klocka och inget processtillstånd, och bygger för wasm32, så ytorna för Python, WebAssembly och server anropar dem oförändrade. Kommandoraden är ett tunt skal runt dem.

Vad ett paket inte gör#

• Det kör inte om bedömningen. Den som har hela loggen och config.json kan köra om kshana receiver-trust och jämföra med epochs.json; paketet bevisar vad som registrerades, inte att motorn hade rätt.
• Det bevisar inte att loggen är äkta eller fullständig. Hashvärdet av hela loggen knyter registreringen till en fil; var den filen kommer ifrån är upp till operatören att fastställa.
• Det innehåller inget prestandapåstående om detektering eller avvisning av störning.
• Det är en teknisk registrering och inte ett juridiskt utlåtande eller en certifiering.