Nachweispakete: ein signierter Bericht über ein GNSS-Vertrauensereignis

Ein Paket ist ein technischer Bericht, keine Rechtsauffassung. Es hält fest, was die Kshana-Engine aus einem angegebenen Empfängerlog unter einer angegebenen Konfiguration berechnet hat, und lässt jeden prüfen, dass nichts darin nachträglich geändert wurde. Es sagt nicht, was ein Ereignis verursacht hat, wer verantwortlich war, ob eine Pflicht erfüllt wurde oder dass das Log zeigt, was der Empfänger tatsächlich empfangen hat. Das Manifest und die Zusammenfassung sagen beides.

Ein Nachweispaket dient einem Vorfallbericht, einem Versicherer oder der Frage einer Aufsichtsbehörde: „Was hat Ihr System zwischen diesen beiden Zeitpunkten über das GNSS-Signal gesagt, und können wir diesem Bericht vertrauen?"

Ein Paket erstellen#

# 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

Bei einem Paket aus einer Laborsitzung hält --lab-attestation lab.toml die Angabe des Bedieners zum Aufbau (leitungsgebunden oder abgeschirmt, Dämpfung oder Gehäuse, was HF ausgesendet hat) im signierten Manifest fest; siehe HARDWARE-SAFETY.md. Sie wird so festgehalten, wie sie angegeben wurde, und nie überprüft.

--from und --to sind Sekunden seit der ersten Epoche des Logs oder eine ISO-8601-UTC-Zeit, wenn das Log seine eigene Startzeit angibt. --out darf nicht bereits Dateien enthalten. --created-utc nimmt eine echte UTC-Zeit wie 2026-01-02T03:04:05Z (alles andere wird abgelehnt) oder none entgegen, wodurch die Erstellungszeit entfällt und das Paket Byte für Byte reproduzierbar wird. Die Erstellungszeit ist, was der Signierende angibt; nichts prüft sie gegen eine Uhr, wofür das optionale Zeitstempel-Token da ist.

Die Schlüsseldatei enthält einen 32-Byte-Ed25519-Seed als 64 Hexziffern; geben Sie Ihren eigenen an (zum Beispiel einen, der in Ihrem Schlüsselverwaltungssystem liegt) oder lassen Sie keygen einen erzeugen. kshana warnt, wenn die Datei für andere Benutzer lesbar ist. .gitignore schließt *.evidence-key aus; benennen Sie Ihren Schlüssel so, wenn er in einem Checkout liegt.

Was in einem Paket enthalten ist#

Log-Ausschnitt. Der Reader meldet den Quell-Byte-Bereich jeder Epoche, sodass der Ausschnitt der kleinste Byte-Bereich ist, der jede Epoche im Zeitfenster enthält (byte-range): NMEA, u-blox UBX, RINEX-3-Beobachtungen und Android-Logs. Er wird als rohe Bytes gehasht, nie als dekodierter Text. Bei einem Live-Feed oder RINEX 2 gibt es keinen Bereich; dann wird das ganze Log gebündelt, und das Manifest sagt whole-log (das Zeitfenster begrenzt, welche Epochen gemeldet werden, nicht welche Bytes enthalten sind). Die Zusammenfassung gibt an, welcher Fall zutrifft. Ein Ausschnitt ist ein Bericht über die Bytes des Zeitfensters, kein eigenständiges Log: Ein RINEX-Ausschnitt hat zum Beispiel keinen Dateikopf.

Hash-Kette. Das Manifest führt die Dateien in fester Reihenfolge auf. link₀ = SHA-256("kshana- evidence-chain/1"); für jede Datei linkᵢ = SHA-256(linkᵢ₋₁ ‖ SHA-256(file) ‖ len(name) ‖ name) (Länge als 4 Bytes, Big-Endian). Das letzte Glied ist chain_head. Das Umsortieren, Entfernen oder Ersetzen einer Datei ändert die Kette; die Signatur deckt die Kette ab.

Ein Paket verifizieren#

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

Exit-Status 0 bedeutet verifiziert; 1 bedeutet, dass etwas fehlgeschlagen ist; 2 bedeutet einen Aufruffehler; 3 bedeutet, dass das Paket intakt ist, sein Signierender aber nicht gepinnt war (siehe unten). Jede Prüfung meldet bestanden, fehlgeschlagen oder übersprungen, und jeder Fehler wird benannt:

Die Änderung eines einzigen Bytes in einer beliebigen Datei lässt die Verifikation mit dem passenden Grund fehlschlagen: Ein geändertes Artefakt wird als Hash-Abweichung dieser Datei gemeldet und sonst nichts; ein geändertes Manifest lässt die Signatur fehlschlagen. Das erneute Berechnen von Hashes und Kette nach dem Bearbeiten einer Datei hilft ohne den Signierschlüssel nicht; dann schlägt nur die Signatur fehl.

Den Schlüssel pinnen. Ohne --pubkey beweist ein Paket nur, dass es gegenüber dem Schlüssel intakt ist, den es selbst nennt und den jeder erzeugen kann. Die Verifikation beendet sich dann mit 3 und sagt „INTACT, BUT THE SIGNER IS NOT PINNED" statt „VERIFIED"; --allow-unpinned akzeptiert den eigenen Schlüssel des Pakets wissentlich und gibt „VERIFIED against the key the pack names itself (signer NOT pinned; pass --pubkey)" aus. Beziehen Sie den öffentlichen Schlüssel des Signierenden auf einem vertrauenswürdigen Weg vom Signierenden (nicht aus dem Paket) und übergeben Sie ihn mit --pubkey: 64 Hexziffern oder die Datei .pub. Die versehentliche Übergabe des privaten Schlüssels wird erkannt und abgelehnt. Der Fingerabdruck (die ersten 128 Bit des SHA-256 des Schlüssels, 32 Hexziffern) wird zum Vergleich von Auge ausgegeben; den vollständigen Schlüssel zu pinnen ist der verlässliche Weg.

Paketformat und Verifikationsverfahren (normativ)#

Dieser Abschnitt ist die Spezifikation, nach der ein unabhängiger Verifizierer geschrieben wird. Wörter in Großbuchstaben sind Anforderungen. Ein Paket ist ein Verzeichnis (oder eine beliebige Abbildung von Dateiname auf Bytes) aus Dateien, die genau wie unten benannt sind; ein Verifizierer arbeitet mit den Bytes jeder Datei, wie sie gespeichert sind, und serialisiert nie etwas neu.

Dateien. Die Artefaktdateien sind in dieser festen Reihenfolge log-slice.bin, config.json, epochs.json, summary.html. Ein Paket hat außerdem manifest.json und manifest.sig und KANN timestamp.tsr haben. Jeder andere Name ist eine nicht aufgeführte Datei.

Hex. Jede Hex-Zeichenfolge besteht ausschließlich aus Kleinbuchstaben 0-9a-f und enthält keine Leerzeichen; Großbuchstaben werden nicht akzeptiert. SHA-256-Werte haben 64 Ziffern, der öffentliche Schlüssel hat 64 Ziffern, die Signatur hat 128 Ziffern.

manifest.sig. Das Kleinbuchstaben-Hex mit 128 Ziffern der 64-Byte-Ed25519-Signatur (RFC 8032, das reine Ed25519-Verfahren) über die exakten Bytes von manifest.json, gefolgt von genau einem \n und sonst nichts. Die Signatur MUSS strikt geprüft werden: Eine Signatur, deren S-Wert nicht kleiner als die Gruppenordnung L ist, ist ungültig.

manifest.json. Ein UTF-8-JSON-Objekt. Seine Member (ein Verifizierer MUSS jeden mit dem angegebenen JSON-Typ finden; zusätzliche Member werden ignoriert):

signer.fingerprint sind die ersten 32 Hexziffern des SHA-256 über die 32 Bytes des öffentlichen Schlüssels.

Hash-Kette. link0 ist der SHA-256 der 23 ASCII-Bytes kshana-evidence-chain/1. Für jedes Artefakt der Reihe nach link = SHA-256( previous_link (32 bytes) ‖ SHA-256(file) (32 bytes) ‖ len(name) as 4 bytes big-endian ‖ name as UTF-8 ), wobei SHA-256(file) dem im Manifest festgehaltenen sha256 für dieses Artefakt entnommen wird (die Kette ist also eine Eigenschaft des Manifests und wird gegen dieses geprüft, nicht gegen die Dateien).

Verfahren. Ein Verifizierer führt diese Schritte der Reihe nach aus und sammelt jeden Fehler; das Ergebnis ist die Menge der Fehler, jeweils ein code und, wo angegeben, die Datei name. Er DARF NICHT beim ersten Fehler anhalten, außer wo angegeben. pin ist der öffentliche Schlüssel, dem der Verifizierer laut Vorgabe vertrauen soll, falls es einen gibt.

1. Kein manifest.json: Fehler manifest-missing; anhalten.
2. Wenn manifest.json kein JSON-Objekt mit jedem oben genannten Member in den angegebenen Typen ist (einschließlich artifacts-Einträgen mit jedem Member und log.slice): Fehler manifest-malformed. Andernfalls, wenn format nicht der oben genannte Wert ist: unsupported-format.
3. Signaturphase. Diese Phase wird unabhängig davon ausgeführt, ob das Manifest lesbar war. Wenn das Manifest lesbar war, ist der genannte Schlüssel signer.public_key; wenn er nicht aus 64 Kleinbuchstaben-Hexziffern besteht: Fehler public-key-malformed (kein genannter Schlüssel); andernfalls, wenn signer.fingerprint nicht sein Fingerabdruck ist: Fehler public-key-malformed (der Schlüssel bleibt verwendbar). Wenn sowohl ein pin als auch ein genannter Schlüssel existieren und sich unterscheiden: Fehler public-key-mismatch. Der Prüfschlüssel ist pin, wenn einer angegeben wurde, andernfalls der genannte Schlüssel, wenn es einen gibt; mit keinem von beiden gibt es keinen Prüfschlüssel (dies schließt jeden Fall ein, in dem das Manifest nicht lesbar war und kein pin angegeben wurde). Wenn es kein manifest.sig gibt: signature-missing. Andernfalls, wenn die Datei nicht genau 128 Kleinbuchstaben-Hexziffern plus ein \n ist: signature-malformed. Andernfalls, wenn es einen Prüfschlüssel gibt, der keine gültige Ed25519-Public-Key-Kodierung ist: public-key-malformed. Andernfalls, wenn es einen Prüfschlüssel gibt und die Signatur nicht strikt über die Bytes von manifest.json (was auch immer sie sind) verifiziert: signature-invalid. (Ohne Prüfschlüssel wird die Signatur nicht geprüft, und dafür wird kein Fehler ausgelöst.)
4. Wenn das Manifest nicht lesbar war (Schritt 2 ergab manifest-malformed): hier anhalten.
5. Artefakte. Wenn die Namen in artifacts nicht genau die vier oben genannten in dieser Reihenfolge sind: artifact-list-malformed. Dann für jeden Manifesteintrag der Reihe nach: Wenn das Paket keine Datei dieses Namens hat: file-missing (Name); andernfalls, wenn ihre Länge von bytes abweicht: file-size-mismatch (Name); und, unabhängig davon, wenn der SHA-256 der Datei von sha256 abweicht: file-hash-mismatch (Name).
6. Nicht aufgeführte Dateien: für jede Datei im Paket außer manifest.json, manifest.sig, timestamp.tsr und den Namen in artifacts des Manifests: unlisted-file (Name).
7. Kette. artifacts des Manifests der Reihe nach ab link0 durchlaufen. Wenn sha256 eines Eintrags nicht aus 64 Kleinbuchstaben-Hexziffern besteht: manifest-malformed, und die Kette wird aufgegeben (keine Prüfung des Kopfes). Andernfalls das Glied berechnen; wenn es vom link des Eintrags abweicht: chain-mismatch (Name). Nach dem Durchlauf, wenn die Kette nicht aufgegeben wurde und das letzte Glied von chain_head abweicht: chain-head-mismatch.
8. Ausschnitt und Epochen. slice-record-inconsistent auslösen (höchstens einmal je Grund, und ein Verifizierer meldet den Code einmal, egal wie viele Gründe zutreffen), wenn eines davon zutrifft: start > end; end > full_bytes; sha256 des Eintrags log-slice.bin weicht von slice.sha256 ab; bytes dieses Eintrags weicht von end - start ab; oder kind ist whole-log und eines von start != 0, end != full_bytes, slice.sha256 != full_sha256 trifft zu. Wenn epochs.json existiert und als JSON-Array geparst wird, dessen Länge von epochs_in_window abweicht: epoch-count-mismatch.
9. Vollständiges Log. Nur wenn dem Verifizierer die ursprünglichen Log-Bytes übergeben wurden: Wenn deren SHA-256 von log.full_sha256 abweicht: full-log-hash-mismatch; andernfalls, wenn der Bereich start..end nicht innerhalb des Logs liegt oder die Bytes des Logs dort von log-slice.bin abweichen: slice-not-from-full-log.
10. Zeitstempel. Ohne timestamp.tsr: Wenn dem Verifizierer vorgegeben wurde, einen zu verlangen: timestamp-missing; andernfalls nichts. Mit einem: Wenn er sich nicht als RFC-3161-Token oder -Antwort lesen lässt (siehe unten): timestamp-malformed; andernfalls, wenn sein Message-Imprint nicht der Hash der Bytes von manifest.json im eigenen Algorithmus des Imprints (SHA-256, SHA-384 oder SHA-512) ist: timestamp-imprint-mismatch.

Das Paket ist genau dann verifiziert, wenn die Fehlermenge leer ist. Ob der Signierende gepinnt war, wird getrennt gemeldet und ändert die Fehlermenge nicht.

Zeitstempel-Token. Ein Token ist eine DER-ContentInfo, deren Inhaltstyp CMS SignedData (1.2.840.113549.1.7.2) und deren eingekapselter Inhaltstyp id-ct-TSTInfo (1.2.840.113549.1.9.16.1.4) ist; eine Antwort ist eine DER-TimeStampResp (eine PKIStatusInfo, gefolgt vom Token), deren Status 0 oder 1 ist. Der Message-Imprint-Algorithmus der TSTInfo muss SHA-256, SHA-384 oder SHA-512 sein, mit einem Digest der Länge dieses Algorithmus, und ihre genTime eine echte UTC-Kalenderzeit. BER mit unbestimmter Länge wird nicht akzeptiert. Die Signatur und die Zertifikatskette der Behörde werden nur geprüft, wenn vertrauenswürdige Anker angegeben sind (--tsa-ca, unten).

Die Nachweiskennzeichnung (0,40)#

Ein mit 0,40 oder später erstelltes Paket trägt in config.json einen Eintrag evidence (die Stufe, VALIDATED, MODELLED oder PARTNER, die der schwächste Status unter seinen Zeilen ist, sowie die Kennungen und Anforderungen der Zeilen der Verifikationsmatrix, auf denen der Inhalt des Pakets beruht: die Zeile zur Paketintegrität, die Zeilen zu receiver-trust und für diese Pakete die Zeilen zur Jammertest-Bewertung oder zum Rundlauf) und config_version "1.1". Er liegt innerhalb von config.json, sodass der Datei-Hash des Manifests, die Hash-Kette und die Signatur ihn abdecken: Eine Änderung lässt die Verifikation fehlschlagen. kshana evidence verify meldet die Stufe und die Zeilenkennungen.

Die Änderung ist additiv und nur vorwärtsgerichtet. Das format des Manifests bleibt kshana-evidence/1: Der normative Text oben sagt, dass ein Verifizierer diesen Wert finden MUSS, und der Clean-Room-Verifizierer in scripts/ tut das. Die Nebenversion wird daher von config_version getragen (bei einem vor 0,40 erstellten Paket abwesend, was 1,0 bedeutet), nicht von einer neuen Zeichenfolge format. Ein vor 0,40 erstelltes Paket hat keine Kennzeichnung und wird unverändert verifiziert; kshana evidence verify sagt „no evidence label (pre-0.40 pack)“. Die Tests sind tests/evidence_pack_label.rs (einschließlich der eingecheckten Orakelpakete vor 0.40) und tests/evidence_labels_doc_sync.rs.

RFC-3161-Zeitstempel (optional)#

Ein Zeitstempel-Token einer Zeitstempelbehörde zeigt, dass das Manifest zu einem Zeitpunkt existierte, den die Behörde bestätigt. Das Token gilt über manifest.json, wird also angefordert, nachdem das Paket erstellt wurde (beim Erstellen des Pakets lässt sich keines angeben, und create_bundle lehnt ein Token ab, das nicht über genau dieses Manifest gilt):

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 liest das Token (ein reines Token oder eine vollständige Antwort), prüft, dass es gewährt wurde und dass sein Message-Imprint dem Hash von manifest.json entspricht, und gibt die darin genannte Zeit aus. Ohne vertrauenswürdige Anker fügt es „timestamp authority signature not verified by Kshana" hinzu und meldet authority_signature_verified: false; für diesen Teil die Zeile openssl ts -verify oben ausführen. Ein Token, dessen Imprint abweicht, oder eines, das sich nicht parsen lässt, ist ein Fehler. Die Inhaltstypen, die Imprint-Länge und die Erzeugungszeit des Tokens werden auf Plausibilität geprüft.

Mit --tsa-ca authority-ca.pem (ein oder mehrere PEM-Zertifikate, allen wird vertraut) prüft verify auch die Behörde, offline, so wie openssl ts -verify es tut: den Message-Digest der signierten Attribute, die Signatur (RSA PKCS#1 v1.5, RSA-PSS, ECDSA P-256 oder P-384), die ESS-Signing-Certificate-Bindung, die kritische Extended Key Usage timeStamping des Signierenden und die Kette bis zu einem selbst ausgestellten Anker, wobei jedes Zertifikat zur genTime des Tokens gültig sein muss. Ein Fehler wird als timestamp-authority-invalid mit der ersten fehlgeschlagenen Prüfung gemeldet, und authority_signature_verified ist nur wahr, wenn alles bestanden wurde. Die Sperrung (CRL oder OCSP) wird nicht geprüft. Dieser Verifizierer stimmt mit OpenSSL 3.0.13 in 27 selbst erzeugten Fällen überein (tests/fixtures/evidence_tsa/PREREGISTRATION.md).

Das Token liegt neben dem signierten Manifest, nicht darin. Nichts in der Signatur oder der Kette deckt es ab, sodass ein Token entfernt oder durch ein anderes gültiges ersetzt werden kann, ohne dass die Signatur fehlschlägt. verify vermerkt daher, wenn ein Paket keines hat, und --require-timestamp macht ein fehlendes Token zu einem Fehler (timestamp-missing); ein ersetztes Token wird nur erkannt, wenn es nicht zum Manifest passt. attach-timestamp weigert sich, ein vorhandenes Token zu überschreiben, außer Sie übergeben --replace. Wenn ein Zeitstempel für Sie wichtig ist, bewahren Sie das Token und das Verifikationsergebnis bei Ihren eigenen Unterlagen auf und verlangen Sie es.

Aus dem Code#

kshana::evidence::build_receiver_trust_pack ist der eine Einstiegspunkt, den die Befehlszeile und jede andere Oberfläche aufrufen, um ein Paket zu erstellen: Hinein gehen ein Szenario, die Bytes des Logs (und der Navigationsdatei, bei RINEX), das Zeitfenster als Text, ein Titel und eine optionale Erstellungszeit sowie der Signier-Seed; heraus kommen die Dateien, die Epochenanzahl, der Ausschnitt, der Manifest-Hash und der Fingerabdruck des Signierenden. Er liest keine Dateien und keine Uhr, sodass dieselben Eingaben dieselben Bytes ergeben. Darunter sind create_bundle und verify_bundle reine Funktionen: Bytes hinein (EvidenceInput, ein 32-Byte-Seed, eine BTreeMap<String, Vec<u8>> von Dateien), serialisierbare Ergebnisse heraus (Files, VerifyReport). Sie verwenden keine Dateien, keine Uhr und keinen Prozesszustand und bauen für wasm32, sodass die Oberflächen für Python, WebAssembly und Server sie unverändert aufrufen. Die Befehlszeile ist ein dünner Wrapper darum.

Was ein Paket nicht leistet#

• Es führt die Bewertung nicht erneut aus. Jeder mit dem vollständigen Log und config.json kann kshana receiver-trust erneut ausführen und mit epochs.json vergleichen; das Paket belegt, was festgehalten wurde, nicht dass die Engine recht hatte.
• Es beweist nicht, dass das Log echt oder vollständig ist. Der Hash des vollständigen Logs bindet den Bericht an eine Datei; woher diese Datei stammt, muss der Betreiber klären.
• Es enthält keine Leistungsaussage zur Erkennung oder Abwehr von Störungen.
• Es ist ein technischer Bericht und weder eine Rechtsauffassung noch eine Zertifizierung.